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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses the response format (JSON-stat2), the German language of codes/labels, the default all-values behavior of unfiltered dimensions, and the no-auth open-data status. This significantly enriches the operational context an agent needs.

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?

Four dense sentences cover what, prerequisites, response format, language caveat, response-size risk, and authentication. Every clause carries operational value, and the key purpose is front-loaded in the first 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?

The description covers dataset identification, filter construction, output format, language caveat, response-size management, and auth status. Combined with a 100%-covered schema and an output schema present, the agent has everything needed for correct invocation without ambiguity.

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 applies. The description reinforces that database_id comes from catalog.list and filters from table.metadata, and reiterates the filter structure, but it adds no parameter semantics beyond what the schema already states. The time/region tip is more behavioral than parameter-defining.

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 states a specific verb ('Query'), a clear resource ('any Swiss Federal Statistical Office (FSO/BFS) STAT-TAB dataset'), and the mechanism ('using dimension filters'). It also references sibling tools catalog.list and table.metadata, positioning itself as the data-query step in the workflow and distinguishing it from data-discovery tools.

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 workflow guidance: provide a database_id from catalog.list, optionally use filters from table.metadata, and always filter time and region to keep responses manageable. It does not explicitly exclude alternatives like swissfso.wages.monthly, but it provides enough context for the agent to know when this general-purpose query tool is appropriate.

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