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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context: vintage_coverage_starts declares that revisions made before Invokely first retrieved the series are absent, known_until is null for the current version, and truncated signals truncation. It stops short of describing rate limits or auth requirements, which is a modest gap.

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?

Purpose is front-loaded, followed by usage, example, and return shape in a tight progression. The lengthy return-value paragraph is justified because there is no output schema, and each sentence carries distinct information (semantics of revisions vs status_changes vs confirmed_final).

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?

With no output schema, the description fully documents the return object, including nested version fields, summary fields, and the caveat that a value only confirmed as final was not revised. Combined with the citation instruction and vintage coverage limit, an agent has everything needed to call and interpret results.

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 the baseline is 3. The description does add interaction semantics beyond the schema - how period vs from/to select single-period versus range mode, the 60-period cap, and that summary spans the whole range - so it nudges above pure baseline, but the per-parameter details themselves are left to the schema.

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 verb and resource - 'List every version Invokely has kept of a figure' - and immediately scopes it to publisher revisions and status-only changes. It explicitly distinguishes itself from the nearest sibling by naming get_value with as_of for a point-in-time value.

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 concrete user intents ('how was the August CPI revised', 'has this figure changed since it was first published') and an explicit alternative with the condition that selects it (get_value with as_of). It also explains the two operating modes: pass period for one figure, otherwise from/to or nothing yields up to 60 multi-version periods.

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