Diavgis — Greek Public Procurement

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond this by explaining the buyer/supplier distinction, the 'top' selection criteria, and the inclusion of act counts and EUR totals, which are not covered by the 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?

The description is two sentences with no filler. The first sentence front-loads the core purpose, and the second adds a clarifying explanatory phrase. Every part contributes to understanding.

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 simple tool, strong annotations, and existence of an output schema, the description is complete. It covers the essential logic (directional counterparties), the output attributes (counts and totals), and the use case, leaving no significant gaps.

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 coverage is 100% for both parameters (afm and limit), with descriptions already provided. The description adds no additional parameter-level semantics beyond what the schema contains, 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 clearly states that the tool retrieves top counterparties of an entity, with explicit directionality (buyer vs supplier) and output contents (act counts, EUR totals). This distinguishes it from sibling tools like get_entity or rank_entities by focusing specifically on business relationships.

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 a due-diligence use case ('who does business with whom') but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. Usage guidance is mostly implied rather than explicitly articulated.

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 mark the operation safe/read-only, and the description adds substantial behavioral detail: deduplication drops award records, expiry_basis explains date provenance, and computed_from_publication is flagged as systematically early. This is exactly the kind of value beyond structured annotations the dimension rewards.

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 longer than average but every sentence earns its place: definition, use-case value, dedup rule, date-provenance warning, and access constraint. It is front-loaded with the core purpose before caveats.

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 an output schema exists, the description covers everything needed to call the tool correctly: valid horizons, row semantics, deduplication, expiry_basis provenance, access requirements, and parameter coverage is already in the schema. No critical gap remains.

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?

Input schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by explaining that h=0 is free on all plans while 7/30/180 require a paid plan, and by tying horizon choice to the paid product.

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 exact purpose with specific verb/resource: lists Greek public contracts currently running and expiring within 0/7/30/180 days, and contrasts it as the renewal pipeline. This clearly distinguishes it from generic search_tenders or get_entity tools.

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?

Provides strong context for when to use it: paid lead time is the core product, horizon 0 is free, and warns not to present computed dates as published. It does not name alternative sibling tools or explicitly say when not to use them, so it stops short of a 5.

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 discloses that matching is accent- and case-insensitive and that the tool 'returns the closest names with their ΑΦΜ,' which is crucial behavioral information for an agent expecting a single exact match. It also warns that the user must 'pick the right one,' signaling possible ambiguity. This goes well beyond the readOnlyHint/idempotentHint annotations, which already cover safety but not matching semantics.

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 with a distinct job: purpose, usage context, and matching behavior. The most important information is front-loaded, and every clause adds value. There is no filler or redundant restating of the title or annotations.

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, combined with rich annotations (readOnlyHint, idempotentHint, openWorldHint) and a full output schema, gives an agent everything needed to decide when and how to call this tool. It covers the lookup semantics, the multi-result behavior, and the dependency relationship with sibling tools. Nothing critical 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%, so baseline is 3. The description partially reinforces the 'name' parameter semantics by framing it as a fuzzy lookup and hinting at multiple results with 'closest names,' but it adds little detail about 'kind' or 'limit' beyond what the schema already documents. It does not repeat or contradict the schema, but it also does not substantially enrich parameter understanding.

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 opens with a specific verb and resource: 'Resolve a Greek buyer or supplier NAME to its ΑΦΜ.' This clearly distinguishes the tool as a name-to-tax-id lookup, which is different from siblings like get_entity or entity_counterparties that require an ΑΦΜ. The purpose is unambiguous and immediately actionable.

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 exactly when to use the tool: 'Use this first whenever you have a name but no ΑΦΜ.' It explicitly names dependent tools and filters (get_entity, entity_counterparties, buyer_afm/supplier_afm) that need the 9-digit number, and advises picking the right match before calling anything else. This provides both positive and negative usage guidance.

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 indicate read-only, idempotent, open-world behavior. The description adds substantial behavioral nuance: the API may not hold the commitment_ada act, the field can be comma-separated, it is not a chain edge, and external resolution is required. This goes well beyond the 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?

The description is front-loaded with the core purpose, then adds only high-value caveats about commitment_ada and chain semantics. Each sentence earns its place, and the length is justified by the cross-source complexity.

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 output schema exists and annotations cover safety, the description is complete enough: it explains all id formats, output scope, the special commitment_ada behavior, and the important non-chain relationship. Nothing essential 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%, so the parameter is already well documented. The description restates the id formats but adds little beyond the schema. A baseline of 3 is appropriate since the schema carries the parameter-semantics burden.

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: 'Full detail of one act by its id' with the accepted id forms. It also distinguishes the tool from siblings like get_chain by explicitly clarifying that commitment_ada is 'deliberately NOT a chain edge' and from search/entity tools by focusing on a single act lookup.

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 use when one already has an act id and gives explicit when-not guidance: commitment_ada must be resolved at diavgeia.gov.gr, 'not through this API.' It does not explicitly name sibling alternatives such as get_chain or search_tenders, so it stops short of a full 5.

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?

Even though annotations already mark the tool as read-only, idempotent, and non-destructive, the description adds meaningful behavioral detail: chains are reconstructed, carry confidence and link method, and deliberately exclude high-fan-out administrative umbrellas. This prevents an agent from wrongly assuming every reference relationship is merged into the chain.

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 front-loaded with the core definition and chain example, then the source of chain_id, then the important boundary condition. The third sentence is long but earns its place by preventing a costly misuse of the tool. Nothing in the description is redundant with the schema or annotations.

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 one-parameter read tool with an output schema and strong annotations, the description covers the main purpose, how to get the identifier, what the result represents, and a critical exclusion rule. An agent has enough context to invoke it correctly without further investigation.

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 schema only defines chain_id as a required string with zero coverage, but the description compensates by explaining where to obtain a valid value: from the chain_id field of any act. It does not give format examples or edge-case guidance, but for a single opaque identifier this is sufficient and actionable.

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 resource (a reconstructed procurement lifecycle chain), a retrieval action by chain_id, and explicitly contrasts a chain with mere act references, which distinguishes it from sibling tools like get_act. It also gives a concrete example of the chain shape (commitment → award → contract → payments), leaving no ambiguity about what the tool returns.

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?

It tells the agent exactly when to call it: when you have a chain_id, obtained from the chain_id field of any act. It also explains when not to expect a chain — for broad administrative umbrella references cited by more than 25 acts — and directs the agent to the act's own references instead, which is an explicit alternative routing.

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 annotations by explaining the methodology behind the EUR totals: they represent committed procurement value, counted once per procurement, deduplicated across sources and lifecycle stages, while excluding tenders/budgets. This is valuable behavioral context that the user would not know from the annotations alone. No contradiction with readOnlyHint or other 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?

The description is composed of two precise sentences: the first states the core purpose, and the second clarifies a critical nuance about the spend figures. Every word contributes value, with no redundancy or filler, making it both concise and highly informative.

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 tool is simple with one required parameter, a clear output schema, and read-only annotations. The description provides sufficient context for an agent to understand the output semantics deeply, including the deduplication logic. There is no need to explain return values since the output schema exists, and the description covers business meaning and exclusions.

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 only parameter 'afm' is already well described in the input schema as a 9-digit ΑΦΜ. The description repeats this and adds context about what the profile contains, but does not introduce new parameter-specific constraints or examples. Given the high schema coverage, the description adds little beyond a baseline understanding.

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 that the tool returns a profile of a legal entity by AFM, including name, role, and spend/receipt statistics. This is specific and distinguishes it from sibling tools like get_act and get_chain, though it does not explicitly name alternatives. It is not a tautology and conveys the core function effectively.

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 that this is the tool for obtaining a holistic entity profile, with details on the meaning of the stats. However, it lacks explicit guidance on when to choose this over alternatives such as entity_counterparties or spend_by_cpv. The usage context is implied but not stated directly.

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 declare readOnly, idempotent, open-world, and non-destructive behavior. The description adds meaningful extra context: the call is free and not counted against the quota, and it reflects the current period's allowance, which is behaviorally useful beyond the structured 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?

Two compact sentences front-load the core purpose and returned fields, then add the free-call caveat and a relevant usage tip. Every sentence earns its place with no filler or 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?

The description covers what the tool returns, that it is free/non-counted, and when to invoke it, while an output schema exists to document return values. With no parameters and strong annotations, nothing essential is missing for an agent to select and call this 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?

There are zero parameters, and the empty input schema fully documents that, so the description is not required to explain parameter meaning. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on output semantics instead.

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 tool as a status/readout for the API key's plan, usage, remaining calls, rate limits, and reset time. It is immediately scoped to the API key's current quota, though it lacks an explicit verb, relying on the title and noun phrasing rather than a direct action statement.

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 advises using this before starting a long job, giving a concrete scenario for when to call it. It doesn't mention alternatives or exclusions, but none of the sibling tools overlap with quota-checking, so this is clear, practical guidance.

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 readOnly/idempotent annotations, the description discloses important data behavior: spend is COMMITTED value in EUR, counted once per procurement, deduplicated across sources and lifecycle stages, and tenders are excluded. It also states that results are precomputed and refreshed every 6 hours, making the tool instant and bounded to the top 15.

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 dense and front-loaded, starting with the core purpose and immediately giving defaults and metric semantics. Every clause adds necessary information; there is no filler or repetition of annotations.

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 output schema exists and annotations carry the read-only/idempotent profile, the description fully covers what an agent needs: the exact question types, the metric definitions, the defaults, the limit constraint, and the freshness/performance behavior. No meaningful selection or invocation details are 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 coverage is already 100%, but the description adds significant meaning: it explains what each 'by' value means, clarifies defaults for role and by, and ties limit to the published top-15 dataset. It also specifies the output fields (afm, name, metric, total), surpassing what the schema alone conveys.

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 action ('Rank') and resource ('top Greek public-procurement entities'), then defines the ranking dimensions (role, metric) with concrete defaults and example queries. It clearly separates this tool from spending/lookup tools by focusing on precomputed top-N entity rankings.

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 gives explicit usage context with natural-language question examples such as 'top 10 suppliers by public revenue' and 'which buyers award most without competition'. It does not name alternative sibling tools or exclusion cases, but the intended condition — ranking aggregated entity metrics — is clear enough for an agent to select it.

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 carry readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds three genuinely new behavioral facts beyond them: results come in a paginated envelope where 'next' is a page number or null, natural-person counterparties are redacted, and summing amount_net across results double-counts spend. These materially change how the agent should interpret and use the output.

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 long but dense and purpose-front-loaded: scope first, then filters, then behavioral warnings. The filter enumeration partly restates the well-covered schema, which adds length, but it embeds compound semantics and provenance details that keep nearly every sentence informative. No filler or repetition of annotations.

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 18-parameter, zero-required search tool with an output schema and seven siblings, the description covers all the non-obvious ground: cross-source scope, compound filter usage, pagination envelope shape, redaction behavior, and spend-aggregation routing. Since an output schema exists, return-value details are not the description's job, and nothing critical is left out.

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 coverage is 94%, so the baseline is 3. The description earns an extra point by explaining the non-obvious parameter interplay — deadline_after=TODAY combined with status=tender identifies open tenders — and by clarifying that direct_award, single_bidder, and cancelled are published ΚΗΜΔΗΣ facts rather than arbitrary flags. Most individual parameter semantics, however, remain in 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?

States a specific verb and resource: 'Search Greek public-procurement acts' across three named sources (Διαύγεια, ΚΗΜΔΗΣ, EU TED). The scope is precise, and the closing instruction to 'use rank_entities or spend_by_cpv' explicitly distinguishes it from sibling aggregation tools.

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?

Explicitly names alternatives with the condition that selects them: 'Do NOT sum amount_net across results to get spend — use rank_entities or spend_by_cpv.' It also gives a concrete compound use case — deadline_after=TODAY + status=tender yields the OPEN tenders a supplier can still bid on — so an agent knows when and how to invoke it.

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 annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds the deduplication rule, exclusion of tenders, precomputed nightly refreshes, instant responses, and the exact output fields. This provides rich, non-obvious behavioral context.

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?

Every sentence earns its place. The description is front-loaded with the core purpose, then covers definitions, answer framing, compute model, and routing to the sibling tool, all in only three concise lines.

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 all parameters documented, an output schema present, annotations already covering the read-only/idempotent safety profile, and the description covering output fields, semantics, and alternatives, nothing the agent needs to select and invoke this tool correctly 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 only parameter (year) is clearly documented as a 4-digit year, with omit for all-time in the schema. The description merely reinforces this by saying 'optionally for one year.' Baseline 3 is appropriate since the schema already carries the parameter meaning.

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 opens with a precise verb-resource statement: committed public procurement value by CPV category (2-digit division), and it names the exact answer it provides: top divisions by spend. It differentiates itself from search_tenders by explicitly stating that tenders are excluded and that search_tenders should be used for other divisions.

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?

It gives an explicit use case ('answers what does the Greek state spend the most on') and directly names the alternative path: 'Use search_tenders with cpv= for divisions outside the top list.' This is clear when-to-use and when-not-to-use guidance in the context of the sibling tools.

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