GERDA German Election Data

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds value by disclosing the kind of information returned (coverage, caveats, citation, columns), which goes beyond the annotations and helps set expectations.

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?

One compact sentence with no filler words. It front-loads the action and enumerates the return topics in a scannable list, making efficient use of the description space.

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?

Although annotations cover safety and an output schema exists, the description omits usage routing and parameter semantics. An agent would still need to guess what values 'dataset' and 'column_search' accept, especially with no domain context beyond 'GERDA'.

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 compensate, but it does not explain the 'dataset' parameter format or the purpose of 'column_search' beyond the schema's generic titles. The mention of 'columns' hints at column_search but does not clarify how it behaves.

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 uses a specific verb ('Describe') and names the exact resource ('a GERDA dataset') plus the four content areas covered (coverage, caveats, citation, columns). This clearly differentiates it from siblings like list_datasets, get_download, find_geographies, and query_results.

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?

There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or exclusions. The intended use is only implied by the verb 'describe', which is not enough for an agent to confidently choose it over list_datasets or query_results.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the input types (municipality name or AGS prefix) and the output (GERDA geographic identifiers), which is useful but does not go beyond that. Given the annotations carry the safety burden, a score of 3 is appropriate.

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 a single, front-loaded sentence with no redundancy. Every word contributes to conveying the tool's purpose. It is appropriately concise.

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 return values are covered. However, the two optional parameters (limit and state) are not explained, leaving an agent to guess their effect. For a low-complexity lookup tool, this is a noticeable gap. The description is adequate for the core function but incomplete regarding parameter behavior.

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?

The schema has 0% description coverage, so the description must explain all parameters. It implicitly covers 'query' (the municipality name or AGS prefix) but provides no information about 'limit' (max results) or 'state' (likely a state filter). With two of three parameters undocumented, the description fails to compensate for the schema gap.

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 action ('Resolve') on a defined resource ('a municipality name or AGS prefix') to produce 'GERDA geographic identifiers'. It is distinct from sibling tools (describe_dataset, get_download, list_datasets, query_results) which deal with datasets and downloads, making the purpose unambiguous.

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 implies the use case—resolving geographic names or AGS codes—which clearly differentiates it from siblings. However, it does not explicitly state when not to use it or mention alternative tools. The context is clear enough that an agent would know when this tool is appropriate, but it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds what is returned but does not disclose additional behavioral details such as authentication requirements, link expiration, or format restrictions. This is acceptable given the annotation coverage.

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 a single clear sentence with no filler. It front-loads the core purpose and lists the key outputs efficiently, making it easy to scan.

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 tool is simple, read-only, and backed by an output schema, so the missing return-value detail is not a major issue. However, the complete absence of parameter semantics and usage guidance leaves gaps for an agent trying to call the tool with the correct format or decide when to use 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 description coverage is 0%, and the description does nothing to explain the 'dataset' or 'format' parameters. It never mentions that a dataset is required or what values 'format' accepts, placing the full burden on an already sparse schema.

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 uses a specific verb ('Return') and names concrete outputs (full-file URL, checksum, citation, usage notes), making the tool's purpose clear. It is distinguishable from sibling tools like list_datasets and query_results, though it does not explicitly name or contrast a sibling.

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?

There is no guidance on when to use this tool versus alternatives such as describe_dataset or query_results. The description implies it is for retrieving download-related metadata, but it provides no context, prerequisites, or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe. The description adds a crucial constraint: only GERDA datasets are listed (not all datasets on the server), which is valuable context beyond the annotations.

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?

Single sentence, under 10 words, with the key qualifier ('GERDA') front-loaded. Zero waste.

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 no-parameter, list operation with a given output schema, the description is mostly complete. It might be improved by hinting at the output structure (e.g., a list of dataset names), but the presence of an output schema reduces that need. What else is missing is minimal.

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?

No parameters, so the schema provides no parameter info. The description compensates by clarifying that it's a server-wide listing of GERDA datasets, which is the only semantics needed. Baseline for 0 params is 4, and the description leverages that well.

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 ('List') and resource ('GERDA datasets'), and mentions the server scope. It is distinguishable from siblings like describe_dataset and query_results, but could explicitly differentiate itself from find_geographies which might overlap in listing data.

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?

Clearly implies listing all available datasets, which is appropriate for initial exploration. However, it does not explicitly state when to use this over describe_dataset or query_results, nor does it mention alternative tools for more specific searches.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context by stating the result is 'bounded' (respecting limit/offset) and 'reproducible' (deterministic ordering/selection), which is not captured in annotations. No contradiction with openWorldHint=false or destructiveHint=false exists.

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 a single 11-word sentence with no filler or redundancy. It is front-loaded with the action verb and defines the core constraint in the first clause. Every word contributes to the meaning, achieving high information density without sacrificing clarity.

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?

Despite having an output schema, the description is inadequate for a tool with 8 parameters and zero schema coverage. It leaves unknown what metrics are required, how the filter parameters interact, what a 'GERDA dataset' is, and how pagination or ordering works beyond the vague 'bounded, reproducible.' An agent would still need substantial external knowledge or experimentation to call this correctly.

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 compensate for the 8 parameters, but it does not. It mentions 'subset' and 'bounded' which allude to filtering and limit/offset behavior, but it never explains what 'dataset', 'metrics', 'ags', 'years', 'states', or 'counties' mean within this domain. The description adds almost no value beyond the raw parameter names listed in the schema.

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 uses a specific verb ('Return') and a clear resource ('bounded, reproducible subset of a published GERDA dataset'), making the core purpose obvious. It does not explicitly contrast with siblings like get_download or describe_dataset, but the focus on 'subset' versus full datasets is mildly distinguishing. The phrasing is clear enough that an agent won't confuse it with list_datasets or find_geographies.

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 offers no guidance on when to use this tool versus siblings; alternatives are not named. It does not mention conditions for choosing query_results over get_download, describe_dataset, or list_datasets. The agent is left to infer that this tool returns data rows, but there is no explicit 'use when' or 'prefer X instead' statement.

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