Snap Router — task to the right tool

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

Annotations already mark readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful operational context beyond the annotations: one vector pass, ~200ms, no LLM call, hybrid keyword-fill, and the fact that it returns ranked shortlists with price and compatibility hints. It doesn't detail failure behavior or pagination, but for a discovery tool with rich annotations, the added behavioral context is solid.

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 dense but every sentence earns its place: what it is, what it returns, how it works, when to call it, what it is not, and an example. The key distinction ('DISCOVERY, not execution') is front-loaded, and the NOT-for clause prevents misuse. No fluff, no repetition of schema field names beyond necessary context.

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?

For a tool of moderate complexity with a 100% documented schema, a rich output schema, and four safety-relevant annotations, the description fully equips an agent to use it correctly. It explains the tool's role, its performance characteristics, its filtering options, and its boundaries relative to siblings. There is no missing guidance that would cause an agent to misinvoke it.

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 description coverage is 100%, so the schema already documents all four parameters. The description adds value by clarifying the primary 'task' parameter with an example and by describing the result-shaping semantics of k, registries, and max_price_usdc implicitly through the ranked-shortlist context. It doesn't walk through each parameter in prose, but the schema covers that; the description adds enough extra meaning to earn above baseline.

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 opens with a crisp verb+resource pair ('DISCOVERY, not execution') and immediately distinguishes the tool from execution-oriented siblings. It explicitly says what it returns (ranked shortlist with price and 'works well with' hints) and names what it is NOT for (on-chain token data, pointing to sibling tools). An agent can confidently tell this apart from token_report, token_depth, honeypot_check, and the other siblings without opening schemas.

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 an explicit 'Call this FIRST' rule, specifies the when (whenever you do not already know which tool serves a task), and names exclusions ('NOT for on-chain token data itself (use token_report / token_depth / etc. for that)'). It even provides a concrete example task. This is textbook when-to-use guidance with alternatives listed.

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