search_awards

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses two important behavioral traits: uneven canton coverage (absence is not proof of no award) and the fact that the filter matches the newest publication, so corrected projects drop out. These are non-obvious and useful for interpretation, adding value beyond the structured hints.

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 well-structured with a use_case tag, a concise summary, and two clearly labeled caveats. Every sentence adds value: it identifies the tool's niche, explains its wrapper nature, and provides practical caveats. No fluff or repetition.

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 purpose, usage, and key limitations. It does not mention pagination behavior or response structure, but an output schema exists to cover that. For a tool with this complexity, it is sufficiently complete, though a brief note on pagination (like the canton_match 'both' mode giving up pagination) would elevate it further.

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 context signal indicates schema description coverage is 0%, so the description carries the burden. However, it only explains one parameter (canton_match), saying it 'works exactly as in search_procurements' and defaults to procuring body. The other five parameters (canton, cursor, language, published_from, published_until) are not elaborated in the description text, leaving a significant gap if the schema descriptions are not reliable.

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 the tool's purpose: 'Find who won, not what is open — all four award types at once' and 'Search only awarded contracts (who won).' It distinguishes itself from sibling tools like search_procurements by framing it as a convenience wrapper for completed procurement, making it immediately clear when this tool is appropriate.

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?

Explicit usage guidance is provided: 'Use when the question is about completed procurement rather than current opportunities.' It also names an alternative (get_publication_history) for cases where awards might be missed due to the newest-publication filter, and explains the coverage caveats. This goes beyond simple 'when to use' to include when not to rely on it.

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