cpv_codes_search

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

No annotations are provided, so the description carries the full burden. The description indicates it returns matching codes with descriptions, which is some behavioral disclosure, but it's largely a safe read/search operation. It doesn't disclose whether the tool is read-only explicitly, doesn't describe pagination/filtering behavior beyond the limit param, and doesn't clarify if it's a static lookup or hits an external API. For a search tool with no annotations, this is adequate but thin.

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 compact — two sentences that cover purpose, usage domain, and return format. It's front-loaded with the primary action and then contextualizes the domain. No redundancy or filler. Minor deduction for not being more explicit about the return value shape or adding usage guidance.

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 simple search/lookup tool with 2 well-documented parameters and no output schema, the description covers the essentials. It explains what CPV codes are, where they're used, and what the tool returns. However, it doesn't mention the sibling nc_codes_search for comparison, and doesn't clarify edge cases like exact vs. fuzzy matching or the meaning of the returned code format.

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 both parameters (search query and limit). The description adds context that search matches by 'code number or description text', which reinforces the search parameter's semantics. However, it doesn't go beyond what the schema states for either parameter, so the baseline of 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?

The description clearly states a specific verb+resource: 'Search CPV classification codes by code number or description.' It distinguishes itself by noting CPV codes are used in e-Transport declarations and public procurement, and explains the return format ('matching codes with their descriptions'). However, it doesn't explicitly differentiate from its sibling nc_codes_search, which appears to be an analogous tool for NC codes.

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 usage context — searching CPV codes for e-Transport and procurement purposes. However, it provides no explicit when-to-use vs. when-not-to-use guidance, and doesn't mention the alternative nc_codes_search (for NC codes) that an agent might confuse this with. The context around CPV codes is helpful but no exclusions or alternative tool references are given.

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