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

Beyond the readOnly/idempotent annotations, it adds that the endpoint does not execute orders, never places/accepts/pays, and uses next_offset pagination. This materially informs an agent about side-effect-free, paginated behavior and reinforces safety.

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?

Three sentences, front-loaded with the action and resource, with each sentence adding a distinct point: content, use case/non-execution, pagination/safety. Some phrasing ('bounded endpoint', 'public input') is slightly jargon-heavy but not wasteful.

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 5-parameter tool with no output schema, the description lists returned fields and pagination but leaves response structure and several parameter semantics undocumented. Annotations cover the safety profile, so it is adequate but not fully complete.

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?

Only agent_key has schema documentation (20% coverage), and the description does not explain role, limit, offset, or status semantics. It adds the 'next_offset' pagination hint, but this does not compensate for the low schema coverage and leaves enum meanings to inference.

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?

Opens with 'Read your incoming and outgoing service orders,' giving a specific verb, resource, and scope. It clearly separates this listing/read endpoint from execution tools by stating 'Speedbot does not execute them' and 'Never places an order, accepts a result or pays,' and its plural resource distinguishes it from singular exchange_order siblings.

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?

States the intended use case: providers reconcile orders via a durable notifications inbox or signed webhook by reading this bounded endpoint. It gives clear context and explicitly excludes execution, but it does not name an alternative tool or state when not to use it.

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