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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description usefully adds behavior beyond that: results are labeled rows, OECD enforces a result-size limit, and broad queries may be silently truncated. That truncation warning is the kind of operational caveat structured fields cannot express. It doesn't quantify the limit or say what truncation looks like in the response, leaving a small 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 dense sentences that front-load the action, then the two error-prone inputs (flow_ref, key), then the truncation caveat — no filler. Minor defect: a stray unbalanced parenthesis at the end of the key explanation slightly muddies an otherwise tight sentence.

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 annotations covering safety and an output schema covering return shape, the description needs only to cover inputs and limits, which it largely does. The remaining gap is concrete guidance on the result-size limit (the limit parameter has a default of 5000 but the description never connects the truncation warning to it).

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 coverage is 100%, so baseline is 3, but the description adds genuine meaning: it shows the exact composite flow_ref syntax, explains that key is positional with one dot-separated slot per dimension and gives a worked example, and specifies accepted period formats ('2020-Q1', '2020'). That goes well past the schema's terse 'Dot-separated dimension key' and 'Inclusive end period'.

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 specific verb and resource ('Fetch tidy rows from any OECD dataflow') and immediately scopes it with a concrete flow_ref example, so an agent knows exactly what kind of payload comes back. It is clearly distinct from sibling entry-point tools such as search_dataflows or list_curated_flows, which discover flows rather than return their rows.

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 explains the operative choice — 'leave empty to fetch everything' versus narrowing with key dimensions or shorter time ranges — and warns when a query is too broad. It stops short of pointing the agent at search_dataflows to obtain a flow_ref in the first place, but the usage context is otherwise clear with no misleading exclusions.

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