Scoutee

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

Annotations already declare the operation read-only and idempotent, so the description goes beyond them by adding two valuable behaviors: it consumes no quota and resolves duplicate identifiers to the canonical notice copy. These are not available in the schema or annotations and give the agent important call-time 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?

Three sentences, each carrying distinct information: the core return value, its shape, and two edge behaviors (quota and duplicate canonicalization). Nothing is redundant, and the most important action 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?

For a simple single-parameter read tool with a rich annotation set and an output schema, the description fully covers what an agent needs: purpose, identifier source, return shape, quota impact, and duplicate-handling behavior. No meaningful guidance is missing.

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%, and the parameter's schema description ('Scoutee identifier of the notice') matches the tool description. The description adds no extra meaning beyond the schema, so the baseline score of 3 applies.

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 precise action: returning one notice in full, keyed by the Scoutee identifier from a search result. It also distinguishes itself from the sibling search_tenders by referencing the 'id of a search result' and 'same shape as a search result', so an agent can easily tell them apart.

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 clearly implies when to use the tool: after obtaining a Scoutee identifier from a search result, to retrieve the full notice. It does not explicitly name alternatives or state when not to use it, but the connection to search results and the sibling tool context makes the usage scenario clear.

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?

Adds substantial behavioral context beyond the annotations: each search consumes a quota unit (cost/rate-limit disclosure), notices on multiple portals are deduplicated with the other portals listed in `also_on`, results default to open-only and newest-first, and the response payload is summarized (page, total, by_country, quota remaining). None of this contradicts the readOnlyHint, idempotentHint, or destructiveHint 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?

Four sentences of roughly 100 words, with purpose front-loaded in the first sentence and each subsequent sentence carrying a distinct behavioral fact: return payload, defaults, deduplication, quota cost. No filler and no repetition of schema content.

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 an 11-parameter tool with rich annotations and an output schema, the description covers the essential non-obvious behaviors: geographic scope, default filtering/sorting, deduplication, quota consumption, and key response fields. The only notable gap is not signposting the search-to-detail flow toward the sibling get_tender; multi-page navigation is otherwise left to the well-documented schema.

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%, and the schema's parameter descriptions are already unusually rich (prefix word-matching semantics for q, cached-translation behavior for keyword, currency notes for min_value). The description's only parameter-related addition is tying the `by_country` response field back to the country parameter, which the schema already documents. Baseline 3 applies since the schema does the heavy lifting.

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 and resource ('Search Scoutee's index of public procurement notices from Europe and North America'), giving geographic scope and the multi-notice return ('a page of notices'). This clearly distinguishes it from the sibling get_tender, which is a single-notice fetch rather than an index search.

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 conveys clear usage context: defaults ('Open notices only and newest first unless asked otherwise'), deduplication behavior, and quota consumption. However, it never explicitly addresses when to use search_tenders versus the sibling get_tender, nor states any when-not-to-use condition; routing to the sibling is left entirely to inference from the verb.

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