resolve_ref

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the search strategy (exact slug, exact alias, case-insensitive name substring) and the return format (ranked candidates with ref/source/score). However, it doesn't describe things like max candidate count, failure behavior, or whether this performs any side effects — though the read-only nature is strongly implied (it returns candidates, doesn't write).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded. The first line states the core purpose with illustrative examples. The second paragraph adds search strategy and return format in a single dense sentence. No wasted words or tautological phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema exists, so return-value details are partially covered. Given the tool's moderate complexity (fuzzy matching with ranking), the description covers the resolution logic, output structure, and use case. It doesn't explain edge cases (e.g., empty results, tie-handling), but for a resolution/query tool this is adequate completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are documented in the schema. The description adds value by explaining the query semantics (fuzzy/nickname-based) and type_filter usage ('restrict to component|repo|task|governance'). The examples given ('the gateway', 'gw', 'auth-gw') add significant meaning beyond the schema's generic 'free text' description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific purpose: resolving fuzzy queries ('the gateway', 'gw', 'auth-gw') to candidate refs. It clearly names the resource type (refs) and the action mechanism (exact slug, alias, case-insensitive substring matching). It distinguishes from siblings by indicating it's a pre-write resolution step, not a list or CRUD operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete guidance: 'call this before writing if the user refers to something by nickname or description.' This establishes the when-to-use context. It doesn't explicitly list alternative tools or when NOT to use it, but the instruction to call before writing is clear enough given the sibling set context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.