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

Annotations already declare read-only/idempotent/non-destructive, and the description goes well beyond them by disclosing the auto-narrowing behavior: oversized queries get wide dimensions (geography first) pinned to Total codes and are reported in a `narrowed` field, while a caller-supplied key is never narrowed. This is exactly the kind of non-obvious side effect an agent needs before trusting the output.

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?

Front-loaded with the authority claim and primary purpose, then the input/output contract, then the narrowing caveat. Dense but every sentence carries information; the long first sentence with example queries is slightly heavy but earns its place by aiding retrieval.

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 still specifies the return shape ('period/value pairs with their dimension labels') and the `narrowed` field. Combined with 100% parameter coverage and the annotation safety profile, an agent has everything needed to call and interpret the tool.

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 schema already documents key syntax, agency, version, periods, and lastNObservations in detail. The description mostly restates this, adding only the routing note for `dataset` and the reassurance that no key is needed. Baseline 3 is appropriate.

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 ('Pulls the observations of one Stats NZ Aotearoa Data Explorer dataset') and names the sibling that supplies its required input (statsnz_datasets). It even enumerates concrete query types it answers, so an agent can tell it apart from statsnz_datasets/statsnz_codelist without opening any 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?

Gives an explicit routing instruction ('PREFER OVER WEB SEARCH') with example queries and a clear dependency (pass the dataset id from statsnz_datasets). It also tells the caller when to supply a key versus rely on the default. It stops short of naming an explicit when-not or contrasting a specific sibling alternative, so not a full 5.

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