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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by disclosing the output structure (requestId, answer, citations with id/title/url, costDollars), expected latency (2.1 seconds) and citation count (8), and flat billing ($0.08). It also clarifies the roles of text and outputSchema. No contradictions with annotations; the description adds substantial behavioral context.

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 yet information-dense. It front-loads the core purpose, then systematically covers parameters, output, performance, cost, and sibling comparisons. Every sentence earns its place—there is no filler, and the structure leads the agent from the basic action to advanced trade-offs without redundancy.

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, an output schema, cost implications, and several siblings, the description is remarkably complete. It covers the primary use case, parameter roles, return fields, latency, cost, and clear routing to alternatives. There is no critical gap that would prevent an agent from selecting and invoking the tool correctly. The only minor omission is error handling or rate limits, but given the tool's simplicity and the annotations, this is not a significant gap.

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 all parameters are documented in the schema itself. The description adds contextual meaning by explaining that query is required, text includes source text, and outputSchema shapes a structured reply, tying them to the tool's purpose. However, it does not elaborate on the type enum values or the structure of outputSchema beyond that, so while it adds value, it does not fully compensate for what the schema already covers. A score of 4 reflects that it goes beyond a simple repetition but stops short of deep parameter guidance.

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 states a clear, specific action: 'Ask a question and get a written answer with citations.' It distinguishes itself from siblings by naming post_exa_agent_runs, post_exa_search, and post_perplexity_sonar, and explains its position between search and research. An agent can immediately understand what this tool does and how it differs from related tools.

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 gives when-to-use and when-not-to-use guidance: it says this tool is 'faster and cheaper than post_exa_agent_runs' and 'more direct than reading post_exa_search results yourself.' It also names an alternative, post_perplexity_sonar, with a cost comparison and a condition to choose it ('reach for Exa when the retrieval needs to be semantic'). This leaves no ambiguity about selection criteria.

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