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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it is not a calibrated probability or guarantee; empty service_suggestions means show nothing; public reads exclude test offers; authenticated test requesters can inspect their own test Work against test services only, with is_test labels; other test accounts cannot read that route. It also states 'No model call, external search, message, order or payment,' which is a strong behavioral boundary. The only minor gap is that it doesn't describe the exact response shape, but with no output schema and the readOnly annotations, the description carries the burden well.

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. It front-loads the core purpose in the first sentence, then covers constraints, exclusions, test behavior, and side-effect boundaries. It is longer than ideal, but for a tool with complex exclusion rules and test-account behavior, the length is justified. The structure is logical: purpose → matching logic → negative cases → test behavior → exclusions → follow-up → side-effect disclaimer.

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?

Given the tool's complexity (matching against contracts, exclusions, test-account routing, no output schema), the description is remarkably complete. It covers what the tool does, what it doesn't do, when results are empty, test-account behavior, and side-effect boundaries. The only missing piece is the exact response format, but the description explicitly says 'Empty service_suggestions means show nothing,' which gives the agent the key behavioral contract. The sibling list is large, but the description's explicit exclusions and follow-up instruction ('Read the service before separately authorizing an order') disambiguate it from exchange_services, exchange_read, and exchange_order.

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 50%: intro_id has no description in the schema, while agent_key has a detailed description. The tool description does not explicitly explain intro_id, but it says 'existing Work request,' which implies intro_id identifies that Work request. The agent_key parameter is fully documented in the schema with storage and security guidance. The description adds context about the request being 'explicit public task' and 'full published service contract,' which helps the agent understand what intro_id refers to. It doesn't fully compensate for the undocumented intro_id, but the pattern ^intro_[a-f0-9]{32}$ plus the tool description's 'existing Work request' is enough to infer semantics.

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 and resource: 'Read up to three available catalog services that may help with an existing Work request.' It clearly distinguishes this from sibling tools like speedbot_exchange_services (list services) and speedbot_exchange_order (place an order) by framing it as a suggestion/read operation tied to a Work request. The scope is precise: up to three services, based on a published contract, with exclusions.

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 explicit when-to-use context: use it when there is an existing Work request and you need candidate services. It also states when NOT to use it: ambiguous or unsupported requirements produce no suggestion, and profile seeking tags are not evidence. It names the follow-up action ('Read the service before separately authorizing an order'), which routes the agent to the correct next tool. It also excludes unavailable, own-agent, same-swarm, and same-wallet offers, which helps the agent decide whether to call this tool at all.

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