discover

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

Annotations already mark the tool readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful context beyond annotations: it states 'Read-only — spends no money, needs no API key' and discloses the return shape ('ranked candidates with endpoint URL, price in cents, health and verification flags'). No contradiction.

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 sentence states the core purpose, and the second gives the operational safety and output summary. The final sentence provides clear workflow guidance. Every clause earns its place.

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 read-only discovery tool, the description covers what is searched, optional budget constraints, safety, output contents, and the correct next tool to use. The input schema fully documents parameters, and annotations cover safety, so no critical context is missing even though there is no output schema.

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 query, limit, category, and budgetCentsMax are already fully documented by the input schema. The description adds only a plain-language framing and the budget bound, which does not significantly exceed the schema's own descriptions. Baseline 3 is appropriate.

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 specific verb ('Searches') and resource ('ArisPay marketplace'), then defines the search style as 'capability or plain-language intent.' It also distinguishes discover from its siblings by naming the find → inspect → pay workflow.

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 explicitly instructs when to use the tool: 'Select this to FIND an endpoint; then inspect to price a specific URL, then pay to call it.' This positions discover as the exploration step and clearly separates it from subsequent sibling tools.

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