vergabe-api: German public procurement notices

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

The annotation readOnlyHint=true already indicates this is a safe read operation. The description adds that it is 'FREE' and lists content areas (endpoints, prices, legal notice), which is useful context. It does not describe the return format or any side effects, but for a simple informational tool with read-only annotation, the description adds reasonable value beyond the annotation.

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, compact sentence that front-loads 'FREE' and then lists the covered topics in a clear, scannable format. Every word adds information; there is no fluff or redundancy. It is appropriately sized for a zero-parameter tool.

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 has no parameters, no output schema, and simple informational nature, the description covers what the tool returns: a description of endpoints, prices, payment details, data source, legal notice, and usage instructions. It is sufficiently complete for an agent to know what to expect. The only minor gap is not stating the output format (e.g., text), but this is not critical for a description tool.

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?

There are zero parameters, so per the rubric the baseline is 4. The description does not need to elaborate on parameters since there are none. It correctly focuses on the content of the description rather than parameter handling.

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 the tool's purpose: describing the API service, including endpoints, prices, payment details, data source, legal notice, and usage instructions. It clearly identifies a specific resource (the service) and the kind of information provided. It distinguishes itself from sibling tools that access data (get_tender, search_tenders) by focusing on service metadata rather than data retrieval.

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 by mentioning 'how to use the paid tools' and 'FREE,' suggesting it should be consulted before using paid tools. However, it does not explicitly state when to use this tool versus the siblings, nor does it provide exclusions or alternative guidance. The context is inferable but not explicit.

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?

The description goes beyond the readOnlyHint annotation by disclosing the payment cost, payment mechanism (x402/USDC on Base), and what the caller receives (HTTP URL, payment requirements, notice details). It also clarifies this is a paid call, which is critical behavioral context. Minor gaps like failure behavior on invalid UUID or payment errors prevent a 5.

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 and front-loaded, opening with the critical PAID warning before explaining what the tool does and how to pay. Each of the three sentences carries necessary information without redundancy or padding.

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?

With no output schema, the description reasonably covers what the tool returns (notice details, HTTP URL, payment requirements) and how to complete the payment. It does not describe the exact response format or error handling, but for a single-UUID lookup with one parameter, the provided information is sufficient for an agent to select and call the tool 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?

The single parameter 'id' is already fully documented in the schema as 'notice UUID', giving 100% schema description coverage. The description adds no new information about the parameter beyond reiterating that the tool retrieves by UUID, so it does not substantially improve on 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 clearly identifies this as a tool to retrieve a single procurement notice by UUID, explicitly listing the returned facets (lots, deadlines, links, winners). It is sharply distinguished from the sibling search and stats tools by its single-record retrieval scope and payment requirement.

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 usage when the agent has a specific notice UUID and needs the full details of that one notice, unlike searching or aggregating across tenders. It does not name alternatives explicitly or state when not to use it, but the paid warning and single-record wording provide sufficient context.

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?

With readOnlyHint=true already covering safety, the description adds meaningful behavioral context: it returns exactly 5 items, uses compact fields, sources from a specific domain, is CC0-licensed, and has personal contact data removed. This goes beyond the annotation and helps an agent understand limitations and data handling.

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 and front-loaded: 'FREE' immediately signals cost/sample nature, followed by what is returned, the optional filter, and data licensing. Every clause adds useful information without redundancy.

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, optional-parameter read-only tool, the description covers most operational basics: source, item count, filter option, and data licensing. However, with no output schema, 'compact fields' is vague and an agent cannot know which tender fields will be returned, which is a real gap for deciding whether this tool satisfies a request.

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 the cpv parameter as a CPV code or prefix. The description adds 'optionally filtered by one CPV code' and 'prefix', which reinforces optionality, but does not provide substantial meaning beyond the schema's pattern and examples.

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 identifies the resource ('German public calls for tenders'), the source ('oeffentlichevergabe.de'), and the scope ('5 most recent', 'compact fields'), making the tool's purpose understandable. It is distinguishable from siblings like search_tenders and tender_stats through the 'sample' framing, though it lacks an explicit verb such as 'list' or 'retrieve'.

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 states that filtering is optional but gives no guidance on when to choose this tool versus search_tenders, get_tender, or tender_stats. The word 'FREE' implies a low-cost/sample use case, but this is not explicit and there are no stated exclusions or alternatives.

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?

Beyond the readOnlyHint annotation, the description discloses critical behavior: the tool is paid ($0.01 USDC on Base per call), uses x402, cannot pay on the user's behalf, and returns the exact HTTP URL and payment requirements. This is exactly the kind of payment requirement context annotations do not capture, so the description earns full credit.

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 three dense sentences with no wasted filler. It front-loads the most critical fact (payment required), then states the search purpose, then gives the payment workflow. The 'PAID' in the title is repeated in the first sentence, but the extra detail ('$0.01 USDC on Base per call via x402') justifies the 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?

Given 17 parameters, no output schema, and low schema coverage, the description is not complete enough. It explains the payment flow but does not describe parameter formats, accepted values, response shape, pagination, or how to construct a valid query after payment. An agent would still need to infer most of the tool's operational details.

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% for 17 parameters, so the description must compensate. It names a few filter concepts (CPV, NUTS, deadline, buyer type, value), which maps loosely to cpv, nuts, deadline_after/deadline_before, buyer_type, and min_value, but leaves the majority of parameters—q, kind, sort, limit, since, until, fields, offset, procedure, legal_basis—unexplained. This is insufficient for a high-complexity parameter set.

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 names a specific verb and resource: 'Full-text and structured search over German public procurement notices.' It also lists search dimensions (CPV, NUTS, deadline, buyer type, value), which clearly distinguishes this from get_tender, sample_tenders, and tender_stats. However, the payment caveat muddles whether the tool returns search results directly or only a payment URL, so it is not a perfect 5.

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 instructs when not to use this remote endpoint: it 'cannot pay on your behalf,' so the agent should 'use the local MCP server ... or an x402 HTTP client to get data.' This is explicit and actionable. It does not discuss sibling tools or when search_tenders is preferable to get_tender, but the payment alternative is well covered.

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 provide readOnlyHint=true. The description adds that data is imported, a 30-day time window, and grouping by kind. It also notes it is free, which is a behavioral attribute. No contradiction.

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?

Extremely concise, a single sentence with front-loaded 'FREE' and all key attributes (time window, grouping). No filler.

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 stats tool with no output schema, the description conveys data source (imported notices), time range, and grouping. It does not explicitly specify the response format, but it is implied to be a summary. Given the simplicity, it is sufficiently complete.

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 exist, so the schema fully covers them. The description correctly does not add parameter details, maintaining the baseline of 4 for zero-parameter tools.

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 returns imported notices per publication day for the last 30 days, split by kind. This distinguishes it from siblings like search_tenders (search) or get_tender (single record) by focusing on aggregate statistics.

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 for viewing notice statistics but does not explicitly state when to use it over alternatives or when not to. No mention of use cases or exclusions. The 'FREE' hint suggests no cost, but there is no direct guidance.

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