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

Annotations cover safety (readOnly, non-destructive, openWorld), so the description earns credit by adding non-obvious behavior: the CTR scale is a 0-100 percentage, and the tool returns notConfigured: true when no Bing Webmaster key exists. That failure-mode disclosure is genuinely useful context beyond the annotations.

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?

Front-loads the returned metrics, then the differentiator, then parameter sourcing, then the edge case. Three tight sentences with no filler and no repetition of schema-declared facts.

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?

An output schema exists, so return shape need not be explained. The description still covers the key edge case (notConfigured), the distinguishing capability (pair-level position), and where to derive inputs, leaving nothing an agent needs to call it correctly.

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 coverage is 80%, so structured fields already do most of the work (verbatim page/query, date omission behavior). The description still adds value by insisting query and page be taken verbatim from specific sibling endpoints, clarifying how to supply correct values rather than just what the fields are.

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?

States a specific resource (daily clicks, impressions, CTR, average position) scoped to ONE exact query+landing-page pair on Bing. It also explicitly distinguishes itself from siblings as 'the only Bing endpoint that carries a true pair-level position,' so an agent can differentiate it from get_bing_query_page_stats or get_bing_page_queries without opening a schema.

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?

Gives a concrete use case ('did this page slip for this term?') and tells the agent where to source required parameter values from (get_bing_query_page_stats / get_bing_page_queries). It stops short of stating when NOT to reach for it versus the sibling stats endpoints, but the intended context is clear.

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