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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'AOPX only recommends; it does not execute or pay the provider', which is a critical non-execution trait that prevents misuse. It also discloses the necessity of a follow-up call to feed future recommendations, giving the agent a clear sense of the tool's side effects and lifecycle. While it doesn't cover permissions or rate limits, the core non-mutating behavior is clearly surfaced.

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 concise and front-loaded with the primary purpose, then states the key behavioral caveat, and finishes with the required follow-up. Every sentence adds essential information with no redundancy, making it efficient for an agent to parse.

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 with 4 parameters and no annotations, the description covers the core purpose, modes, and a critical post-execution step, which is useful. However, it fails to describe the purpose of the three optional parameters, and while an output schema exists, it does not mention any return details other than the recommendation_id indirectly. This leaves the agent guessing about parameter meanings and the structure of the recommendation result.

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 0%, so the description must compensate for unexplained parameters. It does explain the required 'mode' enum (ECONOMY and CRITICAL), but it completely omits the optional parameters client_id, max_cost_eur, and max_latency_ms, leaving their semantics unknown to the agent. This is a significant gap for a moderately complex tool.

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 clearly states the tool 'returns a provider recommendation' for a specific 'SEARCH category', which is a concrete verb+resource combination. It also distinguishes itself from sibling tools like report_outcome, public_outcomes, and public_stats, which are about outcome reporting or statistics, not recommendation generation.

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 provides clear context on when to use the tool (to obtain a provider recommendation in ECONOMY or CRITICAL mode) and gives an explicit follow-up instruction to call report_outcome with the recommendation_id. It does not explicitly state when not to use it or name alternatives, but the workflow directive is strong enough to guide correct usage.

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