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

With no annotations, the description fully carries the transparency burden and excels. It discloses the default metadata-only behavior, explains the two independent availability axes (indexingTier and sourceAccessibility) with special handling for 'reindexing' including a stale-chunks warning, marks canServeFile as deprecated and not a content-availability signal, and clarifies that identifiers resolve to a fixed version rather than a mutable state. These are critical behavioral traits that go far beyond what a schema could convey.

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 longer than typical, but every sentence contributes essential context given the tool's complexity. It is front-loaded with the core purpose and then layers in availability semantics. The prose could be slightly more structured (e.g., separated sections for the axes), but it remains dense and useful without 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?

There is no output schema, so the description must compensate by explaining return-related concepts. It does so by naming the key metadata fields, chunkCount, sourceUrl, and the availability axes, and by explaining how to interpret them. Combined with the detailed parameter semantics and usage guidance, the description is complete enough for an agent to use the tool correctly across a wide range of scenarios.

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?

While schema coverage is high (89%), the description enriches parameter understanding by explaining interactions: includeChunks default changed in v2, chunkContentTypes implies includeChunks and includes unknown chunks as a fallback tier, chunkOrder='importance' requires searchId and falls back otherwise, and run_id is explained with a rationale. This adds context beyond the schema's individual field descriptions, although the schema already covers most parameter syntax.

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 opens with a clear, specific verb+resource: 'Retrieve full paper details by ID.' It immediately disambiguates between metadata-only and chunk retrieval, and explicitly names get_chunks as the alternative for section-level content, distinguishing this tool from its siblings. The default behavior is clarified, so there is no ambiguity about what the tool does.

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 explicit decision rules: use get_chunks when indexingTier='full', fetch sourceUrl when sourceAccessibility permits, and resort to get_document for metadata and chunk retrieval. It also advises preferring filtered chunk retrieval over a full chunks dump for long papers and names get_chunks as the alternative for specific sections. This gives the agent clear when-to-use versus when-not-to-use guidance.

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