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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower — yet the description adds real behavioral context: what is returned (canonical fields, resolved entities, CPV labels, cross-source lifecycle chain) and a subtle trap that `commitment_ada` is a pointer, not a chain edge, and must be resolved externally. This is exactly the kind of non-obvious behavior that prevents wrong invocations.

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?

Front-loads the core purpose and return contents, then devotes the remaining sentences to the one genuinely non-obvious semantic caveat. Every sentence earns its place; nothing is 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?

With an output schema present, the description need not describe return values, yet it does so briefly — mildly redundant. It is otherwise complete: id formats, return scope, and the critical commitment_ada caveat are all covered for a 1-parameter lookup 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?

Schema coverage is 100% and the single parameter's schema description already lists the same id forms (ΑΔΑ, kimdis:<ΑΔΑΜ>, ted:<number>), so the description largely restates the schema. It adds only minor value by naming which source system each prefix maps to. Baseline 3 is appropriate when 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 ('Full detail of one act by its id') and enumerates the accepted id namespaces (Διαύγεια ΑΔΑ, kimdis:<ΑΔΑΜ>, ted:<number>). This clearly separates it from sibling retrieval tools like get_chain and search_tenders, which operate on chains or queries rather than a single id.

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?

Gives strong when-not guidance: the `commitment_ada` value is a pointer INTO Διαύγεια that must be resolved at diavgeia.gov.gr 'not through this API', and is explicitly 'NOT a chain edge'. It does not name a sibling alternative for retrieving linked acts (get_chain), but the usage context is otherwise 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?

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, non-destructive, openWorld, so the safety profile is covered. The description adds a genuinely non-obvious behavioral fact not in the annotations: the call is free and excluded from quota accounting. It stops short of describing freshness/latency or error behavior, so it is strong but not exhaustive.

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 tight sentences, front-loaded with what is returned, then cost, then the recommended call timing. Every sentence carries distinct information with no repetition of the title or schema.

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?

A no-parameter, read-only introspection tool with an output schema already describing the returned fields; the description need not restate returns. What an agent needs — what it gets, that it is free, and when to call it — is fully covered.

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 tool takes zero parameters, so the schema-description baseline of 4 applies; there is nothing parameter-level for the description to clarify or compensate for.

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 precise verb+resource (get the API key's quota) and enumerates the exact payload: plan, calls used/remaining, per-minute rate, page-size and pagination caps, and reset timing. No sibling tool (entity/contract/tender lookups) touches quota, so the boundary is unambiguous.

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?

Gives explicit, actionable timing: 'Check it before starting a long job so you can size the work instead of hitting a wall mid-task.' It also removes the usual hesitation about calling a meta-tool by noting the call is free and not counted against quota.

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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds genuinely new behavior: a paginated envelope where 'next' is a page number or null, redaction of natural-person counterparties, and the warning that amount_net cannot be summed for spend. These are non-obvious traits an agent needs before calling.

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?

Front-loaded with the verb, resource and sources, and the most valuable operational rules (open-tender recipe, no-summing warning) are stated crisply. However, the long enumerated filter list partially echoes the input schema, so a few phrases do not fully earn their place.

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 search with an output schema present, the description covers everything an agent needs: source/status vocabularies, signal meanings, pagination semantics, and the aggregation pitfall with the correct alternative tools. Return-value detail is appropriately delegated to the output 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 coverage is already 94%, so the schema carries most parameter meaning, but the description adds cross-parameter semantics: the deadline_after+status combination, and the domain meaning of signals (direct_award = απευθείας ανάθεση, single_bidder = ≤1 bid, cancelled as a published fact). It does not add much beyond the schema for the more mechanical params like page_size or year, keeping this short of a 5.

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?

Starts with a specific verb+resource ('Search Greek public-procurement acts') and immediately scopes it to THREE named cross-linked sources (Διαύγεια, ΚΗΜΔΗΣ, EU TED). This clearly distinguishes it from siblings like get_act, get_chain, rank_entities and spend_by_cpv, which operate on single acts, chains, or aggregates rather than a multi-source 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?

Gives an explicit positive recipe ('deadline_after=TODAY + status=tender ⇒ the OPEN tenders a supplier can still bid on') and an explicit negative rule ('Do NOT sum amount_net across results to get spend — use rank_entities or spend_by_cpv'). Both when-to-use and when-not-to-use with named alternatives are stated.

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.