kasko_list_model_years

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

The readOnlyHint and openWorldHint annotations already indicate this is a non-destructive, open-ended read operation. The description adds that coverage starts at 2012 and the result is a mapping in descending order, which are useful behavioral details beyond the annotations. However, it does not disclose whether the output always includes a fixed set of years or may vary (e.g., if coverage is updated). The annotations cover the safety profile well, so the description's incremental value is solid but not maximal.

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 very concise: three clear sentences covering purpose, usage scenario, and a key behavioral constraint (start year). It immediately states the tool's function, then gives a concrete use case, and wraps with a brief note on the output format. No words are wasted, and every sentence serves a distinct purpose.

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?

Given the tool's simplicity (zero parameters, a mapping output, and clear semantics), the description is complete enough. The output schema exists (though the content is not shown here, but the description mentions the return type), and the start year constraint is disclosed. For a list tool with straightforward behavior, no additional info is needed to enable correct invocation and interpretation.

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 tool has zero parameters, and schema description coverage is 100%. The description does not need to explain parameters since there are none, but it clarifies that no input is required and the call itself is a self-contained check. This achieves a high baseline (4) because the schema is trivially complete and the description confirms the stateless nature.

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 clearly states it lists vehicle model years from the TSB kasko value list, specifying it returns them in descending order. The verb 'list' and the resource 'vehicle model years' are explicit, and it distinguishes from siblings by being a parameterless year-coverage check, unlike tools like kasko_lookup or kasko_get_value which operate on specific entries.

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 explicitly tells when to call this tool: when the user provides no model year, or to verify coverage before querying a specific year. This contrasts with siblings like kasko_list_brands or kasko_list_models which list other entities, and kasko_get_value which retrieves a specific value once a year is known. The guidance is direct and actionable, leaving no ambiguity about prerequisites or context.

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