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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds critical behavioral context: data is refreshed overnight and may miss or misreport granular live state, account_id is resolved server-side and cannot be overridden, and cross-tenant queries are rejected. This goes well beyond the annotations and clarifies limitations an agent must know.

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?

Despite being long, every section earns its place. The core purpose is front-loaded, followed by structured use cases and exclusions. The text is organized with clear labels (USE FOR, NOT FOR) and specific examples, making it easy for an agent to parse and apply. No fluff or 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?

Given the complexity of this tool (many siblings, need to know when to use vs not), the description is thorough. It covers usage, limitations, alternatives, server-side behavior, and cross-tenant restrictions. An output schema exists, so return values are not the description's responsibility. Everything an agent needs to call it correctly is present.

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?

The schema covers the single parameter 'question' with a clear description, so schema coverage is 100%. The description reinforces the natural-language nature but does not add much beyond what the schema already provides. Baseline 3 is appropriate given the schema carries the meaning.

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 specific verb and resource: 'Query the caller's own account CONTEXT from the Metadata.io knowledge base'. It clearly defines the scope as a rolled-up summary of firmographic, campaign history, and experiment performance. It distinguishes itself from siblings by emphasizing this is a periodic roll-up, not live state, and names alternatives like account_level_stats and performance_metrics.

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?

Explicit 'USE FOR' and 'NOT FOR' sections with concrete examples and named alternative tools. It tells the agent when to use this tool (grounding recommendations in account history) and when not to (live state, benchmarks, cross-tenant queries). It even provides a sample question to illustrate the intended use case.

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