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

The description goes well beyond the annotations (readOnly, idempotent, non-destructive) by revealing the underlying model behavior: articles are 99.5% classified with 30 topics, while references have a separate 33-topic model with only ~46% classification. It also explains that topics are assigned offline over full text, meaning they describe content rather than surface word matches, and gives typical min_prob values with mean probability 0.34. This is rich behavioral context not available in 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?

The description is a dense four-sentence paragraph, longer than the calibration HIGH example, but every sentence contributes useful information. It is front-loaded with the core purpose, then adds needed caveats and parameter guidance. Slightly verbose but not wasteful; no fluff.

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 that an output schema exists, the description does not need to detail return values, but it still clarifies important output nuances (e.g., 'read its classified against total_matches'). It provides essential context about topic model differences between articles and references, and explains over_time and min_prob behavior. It is complete for a read-only analytics tool with 10 optional parameters, though it could mention top_n more explicitly, but that is covered by the schema.

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 already has 100% coverage for 10 parameters, so baseline is 3. The description adds practical guidance for over_time ('returns per-year counts for the leading topics') and min_prob ('keeps only articles where the topic is at least that dominant, mean 0.34, so 0.5 strong'), which supplements schema descriptions. It does not cover all parameters, but adds meaningful value for key ones.

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's purpose: distributing a filtered set across precomputed LDA topics, with topics labelled by top terms. It distinguishes itself from keyword counting ('use this instead of keyword counting') and from sibling distribution tools by focusing on topic-based semantic mapping. The verb 'get' plus specific resource ('topic distribution') is precise.

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 tells when to use this tool: 'use this instead of keyword counting to map a corpus' — a direct alternative. It also clarifies the difference between article and reference subsets, and explains how over_time and min_prob can be used for different analytical needs. This provides clear context for tool selection.

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