Agent-Centric Tool Design Principles

These examples and illustrative results are independently authored teaching materials, not measured model results.

Use case

Expose issue lookup to a context-limited agent. Teaching find_issue(project_id,issue_id) returns identity, summary/evidence URL and documented detail access with clear arguments/errors instead of a whole database.

Mechanism

Choose granularity by actual tasks, use stable names/narrow schemas and deterministic identity-bearing output. Fetch detail on demand; lists expose paging/completeness. Errors name field/reason and verified safe next action, not arbitrary issue text as commands. Preserve controllable boundaries for consequential composites.

Bad example

Dump all issues, return bare 400 for bad project and let the model guess targets or follow external-content recovery commands.

Good example

Validate teaching string IDs. Success matches identity/summary/evidence; detail uses documented access. Unknown project identifies the field and verified list_projects capability; denied access differs from no match. Safe next_actions come from the trusted implementation while issue bodies remain data. Check normal/missing/denied/invalid cases without uncontrolled write composites.

Why the change matters

Typed identity/errors reduce guessing and fabricated recovery. On-demand detail limits irrelevant context without deleting evidence access.

Observable expectation

P9/I17 identity matches, invalid project is located, denied is not nonexistent and unavailable detail stays a gap. Inspect sufficient evidence/current follow-up interfaces and no external-body command execution.

No MCP service is built.

Limits

API coverage and workflow tools suit different clients/risks; sources differ and impose no universal granularity. Schema checks do not prove implementation correctness; verify error provenance.