get_figures

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

With no annotations at all, the description carries the full disclosure burden, and it handles the highest-risk trait well: values are raw as printed (percent as 12.01, not 0.1201; amounts in whole DKK), which prevents unit-scaling errors that annotations would never have covered. It also discloses that each figure carries provenance and a verification status. It does not say what happens when a key is unknown or unavailable for the requested year, which is the main remaining behavioral 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?

Three short blocks, front-loaded with what the tool returns, then the value-format warning, then the discovery pointer. Every sentence earns its place: the scaling warning prevents a concrete error class, and the list_figures line prevents an invalid call. No restatement of the tool name or filler.

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?

An output schema exists, so the description is not obligated to document return values, yet it adds the one thing the schema cannot convey: the raw scaling convention and the presence of source/verified/status metadata. For a two-parameter lookup tool this is close to sufficient. Missing only failure behavior for unknown keys or years.

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 0%, so the description must supply meaning for both parameters. It does partially: "income year" clarifies the intent of year, and the list_figures pointer tells the agent where the keys vocabulary comes from. It never states the year format (four-digit calendar year vs. income/tax year bounds) or what a key string looks like, so half the semantic burden still falls on the caller.

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 names a specific verb and resource ("Get Danish tax figures for an income year") and immediately enumerates what comes back with each figure: source, verified date and status. That scope, plus the explicit pointer to list_figures for key discovery, lets an agent separate this retrieval tool from the sibling estimators without opening a schema.

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?

It gives a concrete prerequisite and alternative: "Use list_figures to discover keys," which tells the agent it cannot call this blind with arbitrary key strings. It also prescribes post-retrieval behavior (cite source and income year, flag non-'verified' status). It stops short of saying when to prefer get_figures over estimate_salary_tax or estimate_payslip, so the boundary with the estimation siblings is left implicit.

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