Get a raw series by explicit id

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

Annotations already signal read-only, idempotent, open-world, non-destructive behavior. The description adds materially beyond that: FRED ids return an explanatory disabled response and are never retrievable, country is required for certain prefixes, DBnomics supports dated editions for vintage-pinned reproducibility, transforms are supported, and every response includes a full citation. This gives agents critical behavioral expectations not derivable from annotations or schema.

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 dense but every sentence earns its place: purpose, id formats, required-country caveats, disabled FRED behavior, transform/year support, citation guarantee, and sibling routing. It is front-loaded with the main action and uses compact examples instead of rambling.

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?

For a 6-parameter read-only data fetch with no output schema, the description covers id construction, prerequisites, disabled paths, transforms, year filters, reproducibility, citation behavior, and tool preference. It does not specify output shape or date-filter edge cases, but the rich caveats make false assumptions unlikely. Slightly short of 5 due to no explicit statement of what a successful response actually contains aside from the citation note.

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?

With only 50% schema description coverage, the description compensates well: it explains the series_id syntax for worldbank, imf, dbnomics, and fred; states which prefixes need a country; and clarifies the strict_source behavior. It also names the transform values that match the enum. Minor gap: no explicit meaning or bounds for start_year/end_year, but the overall parameter picture is far stronger than the raw schema alone.

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?

Purpose is explicit and specific: 'Fetch any supported series by explicit id' names the verb, resource, and id-based access mode. It also distinguishes itself from get_indicator by framing this as raw series access, and the 'Prefer get_indicator' line clarifies its niche among siblings.

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 gives clear usage context: when to use series ids by source, which prefixes require country, which ids are disabled (FRED), and when to prefer get_indicator. It does not enumerate all sibling alternatives or exhaustively say when not to use this tool, but the get_indicator guidance plus the explicit id-scoping is sufficient for most agent routing decisions.

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