DatosIA

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

Annotations already declare it readOnly, idempotent, non-destructive and closed-world, so the safety burden is covered. The description adds behavioral value by disclosing the returned facets (coverage, pricing model, live API sources) and the downstream integration with query_data.

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 sentences, fully front-loaded with the resource and its contents, and zero redundant text. Nothing is wasted.

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?

No output schema exists, so the description carries return-value burden, and it does summarize the returned fields reasonably well. It stops short of describing pagination or result limits, leaving a minor gap for a browse-style 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?

With a single parameter at 100% schema description coverage, the schema already documents 'q' (word filter on title/description). The description adds no further parameter semantics, so the baseline 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?

States a specific verb ('Lists') and resource ('datasets contributed by independent publishers') and enumerates what is included (indicators, coverage, pricing model, live API sources). It is distinguishable from generic search/data tools, though it does not explicitly contrast itself with siblings like find_indicators or search_data.

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?

Implies usage by noting the indicators 'can be used in query_data like any other', which hints at the workflow, but there is no explicit when-to-use/when-not guidance or named alternative (e.g., vs find_indicators or search_data).

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 readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds the supported-country scope, which is useful, but says nothing about error behavior for unsupported countries or how the two result shapes differ.

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 tight sentences with the primary operation front-loaded and the country enumeration last, so nothing important is buried. The first sentence is dense but every clause carries information.

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 5-parameter, no-output-schema tool, the description covers the modes and the country domain but leaves output shape, error conditions, and the interaction rules between date/from/to/add_business_days unstated. It is adequate but not fully self-contained.

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 80%; the only undocumented parameter is add_business_days, and the description supplies its meaning ('the date N business days later/earlier') plus the date it is relative to. It also reinforces the from/to versus date pairing. It stops short of stating required combinations (e.g. that add_business_days needs date), which is the remaining gap.

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 two concrete operations on a specific resource: listing public holidays for a country between two dates, and checking whether a date is a business day / offsetting by N business days. The generic name 'calendar' is rescued by the description, and no sibling tool overlaps this domain, so sibling differentiation isn't needed.

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?

Usage is only implied through parameter pairing ('between two dates' for the holiday list, 'a date' for the business-day check). There is no explicit statement of when to pick each mode, nor what happens if the modes are mixed or a country outside the listed set is supplied.

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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by stating the response is the publisher's raw JSON and is capped at 2 MB, which affects how an agent should plan a call. It omits auth requirements and error behaviour.

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 tight sentences with no filler; the capability and its read-only/size constraints come first and the prerequisite tool hint follows. Every clause carries information.

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?

There is no output schema, so the description appropriately describes the return value (publisher JSON, 2 MB cap) and the prerequisite lookup. For a read-only, annotated fetch tool this is largely complete, though failure modes and rate limits are unstated.

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 50%: 'params' and 'source' are documented in the schema, while 'publisher' and 'dataset' have no descriptions. The description partly compensates by clarifying that these are names discoverable via browse_marketplace, but it says nothing about the nested query-parameter object or accepted formats.

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 gives a specific verb and resource: it calls a contributed dataset's live API through datosmcp and returns the publisher's JSON response. It is easy to distinguish from discovery tools like browse_marketplace, but it does not clarify how it differs from near-neighbours such as query_data or search_data, which also retrieve data.

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 explicitly tells the agent to use browse_marketplace first to obtain the publisher, dataset and source names, which is a concrete prerequisite for a call whose three required parameters are identifiers. There is no when-not-to-use guidance or mention of alternatives to this tool itself.

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 establish read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real value by disclosing the return shape (totals, result by bloc, individual deputy votes) that no output schema provides. It does not mention pagination, default limits, or result caps (limit max 50).

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 sentences, purpose first, query facets second, zero filler. The parenthetical examples ('approving a bill in third reading, electing an official, a resolution…') clarify the scope of a 'question put to a vote' rather than 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?

For an 8-parameter, no-output-schema, read-only search tool, the description covers what is searched and what comes back, which is the core need. Remaining gaps are limit/pagination behavior and default date handling, both minor against annotation coverage of safety semantics.

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?

With 0% schema description coverage across 8 parameters, the description carries the burden and mostly delivers: it maps q, initiative ('bill number'), decree, deputy, vote, and from/to ('dates') to searchable fields, and defines the four vote values (favor, contra, ausente, licencia). Only 'limit' is left unexplained, and no date format or matching semantics are given.

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 specific verb and resource ('Plenary votes in Guatemala's Congress') and enumerates what a record contains: totals, bloc results, and per-deputy votes. It also names the domain facets (bill, decree, deputy, vote) that separate it from siblings like search_bills or deputy_record.

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?

Usage is only implied: 'Find by words in the question, bill number, decree, deputy, vote and dates' tells the agent how to query, not when to choose this tool over search_bills or deputy_record. No exclusions or alternative-routing guidance is given.

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 read-only, idempotent, non-destructive. The description adds genuinely useful behavior beyond that: it discloses the rate source (daily central-bank rate where held, otherwise annual average) and that the response reports which was used. It doesn't cover error cases or direction-ambiguity handling, keeping it from 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?

Two tight sentences with no waste; scope, optionality, and rate-source behavior are all front-loaded and dense with signal.

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 helpfully notes that the result indicates which rate was used, and it explains the conversion and inflation modes. Minor gaps remain around default `to` behavior and the default date (though the schema covers the latter).

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 40%, with only date and inflate_to_year documented in the schema. The description clarifies the currency set for from/to and implies inflation semantics, but does not address the meaning of `to` being optional (default target currency) nor that one side must be USD. It partially compensates but leaves real gaps.

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 (converts) and resource (currency amount) with the exact currency scope (USD vs GTQ, HNL, NIO, CRC, PAB, BZD, DOP) and adds the inflation-adjustment capability. An agent can immediately tell what this does and which currencies are in scope.

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?

Usage is implied: convert an amount on a date, optionally inflated to another year. There is no explicit when-to-use/when-not guidance or named alternative, though none of the sibling tools overlap on currency conversion, so this is adequate but unstated.

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 establish the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lowered. The description adds genuine behavioral context by enumerating what the returned record contains — vote categories (for/against/absent/on leave), attendance, and 'recent' bills/votes — which matters since no output schema exists. It loses a point for the undefined 'recent' time window.

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?

One front-loaded sentence identifies the resource first, then lists contents via a tight colon-delimited enumeration. Every listed item corresponds to data the agent will receive, so nothing is 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 and no parameter docs, the description correctly compensates by describing the record's contents. For a simple read-only, single-parameter tool with full annotation coverage, this is nearly sufficient; only input-format and disambiguation 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 0%, so the description must carry the parameter burden. It implies the single 'name' parameter identifies the deputy and that the name is Guatemalan, but gives no format guidance (full name vs. partial, accent handling, disambiguation for duplicate names). Partial compensation for the coverage gap.

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 precise resource — a single Guatemalan deputy's legislative record — and enumerates its contents (bloc, sponsored bills, pass counts, vote breakdowns, attendance, recent activity). This is far more specific than a sibling like party_profile or search_bills. It stops short of a 5 because there is no explicit verb ('retrieve'/'get') and no direct sibling routing 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?

Intended use is clearly implied: call it when you want one legislator's full record. However, there is no when-to-use guidance versus alternatives such as party_profile, congress_votes, or search_bills, and no statement of prerequisites or failure conditions. Implied usage only.

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 readOnlyHint, idempotentHint, non-destructive and non-open-world, so the safety profile is covered. The description adds genuine value beyond that by enumerating the returned fields (rollup rule and weight, source and licence, country coverage), which tells the agent what detail level to expect. It does not mention failure behavior for an unknown id.

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?

One sentence, front-loaded with the verb and resource, with the payload enumerated in a single compact clause. No filler, no 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?

With no output schema, the description carries the burden of describing return values and does so explicitly by listing the fields returned. For a one-parameter read-only lookup, nothing an agent needs to call it 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?

There is a single parameter with 100% schema coverage, and the schema already supplies the id format and a concrete example (FIN.BRANCHES_PER_100K_ADULTS). The description adds nothing about the parameter, so the baseline 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?

States a specific verb (returns the full definition) and resource (one indicator), and enumerates what is returned: labels, definition, unit, rollup rule/weight, source/licence, country coverage. It does not, however, distinguish itself from the sibling find_indicators, which an agent must choose between.

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?

No when-to-use guidance, no prerequisites, and no routing to alternatives such as find_indicators. Use is only implied by the mention of 'one indicator', leaving the agent to infer that an id must first be obtained elsewhere.

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, and closed-world behavior, so the safety profile is covered. The description adds genuine behavioral context beyond that: the result aggregates at the most local level available and tags each value with whether it describes the place, its department, or its country. It still doesn't say what happens on an unknown place or how large the payload is.

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?

A single dense sentence that front-loads the core action and then qualifies the aggregation behavior. The parenthetical topic list is long and partly duplicates the schema enum, which is minor 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?

There is no output schema, so the description must convey the return shape, and it does reasonably well by describing per-value provenance and the local-first aggregation rule. Gaps remain around failure behavior for unresolved places and response size, but nothing essential to calling the 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%, so both parameters are already documented, including the code-or-name format for "place" and the domain enum. The description's topic list partially mirrors the enum values but adds no syntax or format detail beyond the schema; baseline 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 specific verb and resource ("Returns everything datosmcp holds about one place") and enumerates the topic areas covered, so an agent can distinguish it from find_indicators, search_data, or list_places. It does not name any sibling explicitly, so it falls short of a 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?

Usage is implied by the scope: use it when you want a consolidated profile of a single place rather than querying indicators individually. There is no explicit when-to-use/when-not-to-use guidance, no mention of alternatives like describe_indicator or search_data, and no stated prerequisites.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed world). The description adds genuinely new context by disclosing the output shape — nodes and links for a network diagram, including relation kinds and frequency — which matters because there is no output schema. It still omits filtering/pagination behaviour and how the entity name is matched.

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?

A single dense sentence that front-loads the subject (linked people and organisations) and then the output form. No filler or repetition, though the length-to-information ratio is slightly strained by packing relation kinds, frequency and diagram structure into one clause.

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 usefully covers what the return looks like, and annotations cover safety. But for a three-parameter tool at 0% schema coverage it leaves parameter meaning, usage routing against siblings, and limits entirely unspecified, so an agent could still call it incorrectly.

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%, so the description must carry the parameter burden and does not. It never mentions the 'kind' enum (person/org), the 'limit' cap of 100, or how 'name' is interpreted — only a faint hint in 'one public figure or organisation'. The three parameters remain effectively undocumented.

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 specific resource and what it returns — the people and organisations linked to one figure or organisation, with relation kinds and frequencies, as nodes and links. An agent knows what the tool produces. However, it does not differentiate this from close siblings such as entity_timeline or procurement_network, which also operate on the same kind of entities.

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?

There is no when-to-use or when-not-to-use guidance. Given siblings like entity_timeline, procurement_network, party_profile and search_news, an agent gets no help deciding which tool fits a given question; it must infer from the tool name alone.

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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds useful behavioral context beyond annotations: results are newest first, each includes a source headline, and monthly mentions show presence evolution. It does not mention pagination or limit behavior, so not 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?

A single, front-loaded sentence that efficiently conveys resource, source, ordering, and output details. It is somewhat long due to parenthetical examples, but every phrase adds value.

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 return shape reasonably well, but for a tool with five parameters and no output schema it omits critical parameter semantics (from, to, limit, name). An agent cannot confidently invoke the tool with date ranges or limits based on this description alone.

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% across five parameters. The description only indirectly hints at the kind parameter via 'person or organisation'; it says nothing about the required name, from/to date range, or limit. This is minimal compensation for a significant documentation gap.

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 a specific resource: dated relationships and events involving a person or organisation, extracted from news, with source headlines and monthly mentions. It does not explicitly differentiate from siblings such as entity_network or search_news, so it falls short of a 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?

No guidance on when to use this tool versus alternatives like entity_network, search_news, or deputy_record. The description only implicitly narrows use to public figures or organisations, but provides no explicit conditions or exclusions.

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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds useful context by listing what the returned full text contains for each document type, but it does not disclose auth requirements, rate limits, or error behavior.

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, well-structured sentence that front-loads the core action ('Returns the full text...') and then efficiently specifies the document types. Every clause earns its place with no wasted words.

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 carries the burden of explaining return values, and it does so by describing the three document types and their contents. It is largely complete for a simple fetch tool, though it could mention the return format or how to handle errors.

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 input schema already fully documents the single 'id' parameter with an example. The description reinforces that the id comes from search but adds no syntax or format details beyond what the schema provides, so the baseline 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 specific verb (Returns) and resource (full text of a result from search), then enumerates three document types (answer, indicator, place). It distinguishes from the sibling 'search' by focusing on full-text retrieval, but does not clarify overlap with siblings like describe_indicator or enrich_place.

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 phrase 'from search' implies this tool is used after obtaining an id via search, giving implicit usage context. However, there is no explicit when-to-use guidance, no when-not conditions, and no named alternatives for overlapping siblings.

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 and closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: the geographic domain, the entity restriction to legal entities, and the fields returned (certificate status, products, certifier, location codes, source links), though it says nothing about result caps or pagination.

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 with no filler; the scope, certifications and returned fields are front-loaded before the short legal-entity caveat. Dense but every clause carries information.

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 and six optional parameters, the description does cover the nature of the returned data, which compensates partly. However, it omits guidance on how the parameters combine (e.g. scheme vs q), any default for limit, and result-set behavior, leaving gaps for a six-parameter 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 67%, so several parameters (scheme, product, geo) are documented in the schema itself. The description references 'products', 'certifier' and 'location codes' in passing but adds no syntax, accepted values, or defaults beyond what the schema already provides, so the baseline 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?

States a specific verb (Finds) and resource (companies and cooperatives holding certifications), narrows the domain to Central America, and enumerates the certification schemes and returned fields. It is clear what the tool does, though it never names a sibling to distinguish itself from tools like find_suppliers or search_places.

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?

There is no when-to-use or when-not-to-use guidance and no alternative is named. The only usage-shaped statement is the scoping constraint 'Legal entities only', which is a filter rather than a selection rule.

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 readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that results include coverage and rollup behavior, which is useful context, but it doesn't state limits, pagination, or ranking of matches.

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?

A single sentence, front-loaded with the verb and resource, then the return fields. Every clause earns its place with 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 read-only search tool with no output schema, the definition is adequate but doesn't tell the agent how many results to expect, whether the search is fuzzy or exact, or what to do if the topic is ambiguous. It covers the minimum for invocation but leaves notable 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 50%; the 'text' parameter is documented with examples in the schema, but the 'domain' enum lacks a description. The description clarifies that topics can be Spanish or English, which the schema does not state, adding real value beyond the structured fields.

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 (Lists) and resource (indicators) and describes what the results contain (id, unit, rollup, coverage). It is clear but does not differentiate itself from siblings like describe_indicator or search_data.

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 mentions a topic search but provides no when-to-use guidance, no exclusions, and no mention of alternatives such as describe_indicator for deep-diving a single indicator or search_data for values.

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, closed-world. The description adds scope the annotations cannot: the four covered jurisdictions and the fact that results describe historical public-procurement awards with buyer relationships. It does not mention result limits or pagination, which is the only remaining gap.

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 tight sentences: the first front-loads what the dataset contains, the second delivers the one operational instruction. No filler or repetition of schema fields. Could be marginally sharper by folding the localization hint into 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?

With no output schema, the description correctly spends its words explaining the shape of the return (what was sold, how often, for how much, main buyers) and the language of the input. Annotations cover the safety profile. Only the `limit` parameter and result-count behavior are left unexplained.

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%, so the description must carry parameter meaning. It usefully constrains `q` to Spanish-language procurement terms and its examples imply that the query should be a product/service noun. The `country` enum is implicitly covered by listing the four countries, but `limit` is never addressed and no format/syntax detail is given for `q`.

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 concrete resource — companies that have sold goods/services to the governments of GT, HN, DO, PA — and specifies the data returned (what they sold, frequency, amounts, buyers). It is clearly distinct from neighboring search tools, though it never names the closest sibling (find_certified_companies). Framed as a noun phrase rather than a verb, but the intended action 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 actionable query-authoring guidance ('Search in Spanish') with three concrete example queries, which is genuinely useful. However, it never states when to use this tool versus procurement_network, find_certified_companies, or similar_awards, so routing must be inferred from the data description.

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, and closed-world, so safety is covered. The description adds real behavioral context beyond that: the 90-day window, the exclusion of already-answered topics, and the aggregate output shape (distinct requester counts, countries).

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 sentences, front-loaded with the core definition before the usage hint. Every clause carries information: scope, time window, output fields, and purpose. No 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?

There is no output schema, so the description correctly carries the burden of describing returns (topics, distinct requester counts, countries) and the 90-day scope. It omits any mention of ordering or volume limits, a minor gap for a short read-only list tool with fully documented parameters.

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 both filters (q, country) are already documented in the schema. The description adds nothing about filtering behavior, so the baseline 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?

States a specific verb ('Lists') plus a narrowly scoped resource: unanswered topics requested in the last 90 days, with request counts and countries. This scope is distinct enough from siblings like search_data or browse_marketplace that an agent can recognize it without ambiguity.

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?

'Useful to see what data is missing, or what a dataset in the marketplace could supply' implies the intended use case, hinting at a relationship with browse_marketplace. However it never states when to prefer this over alternatives (e.g. report_data_issue for logging a gap) or any exclusions, leaving routing to inference.

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, closed-world behavior, so safety is covered. The description adds genuinely new behavioral context not derivable from the schema: the default result set is countries and groups (the `level` enum only lists department/municipality/district), and each record includes names, centre coordinates and area. That is meaningful disclosure beyond the structured fields.

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?

A single dense sentence that front-loads the verb and resource, then the default scope, then the drill-down option and returned fields. No filler, though the clause stacking makes it slightly hard to parse.

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 usefully names what comes back (names, centre coordinates, area). It covers both the no-argument default and the filtered hierarchical case, which is the main thing an agent needs; pagination or result-size behavior is the only notable omission.

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 67%: `name` and `within` are documented in the schema, while `level` carries only an enum with no description. The description partially compensates by explaining the hierarchy (departments/municipalities/districts nested under one country or department), clarifying the level/within interplay, but it adds little beyond the schema's own wording for name and within.

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 specific verb and resource ("Lists place codes") and spells out both operating modes: the default countries/groups listing and the hierarchical drill-down by level within a country or department. It does not explicitly name the sibling search_places or contrast list-style enumeration with search, so it stops short of full sibling differentiation.

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?

Usage is implied through the default-vs-filtered framing ("by default, or the departments... of one country or department"), which tells the agent roughly when to supply `within`/`level`. However, it never states when to prefer this over search_places, nor any exclusions or prerequisites.

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 this a safe, idempotent, closed-world read. The description adds value beyond that by disclosing a behavioral trait the annotations cannot express: 'This call is free,' so invoking it never consumes the balance, plus the differing billing models for Free vs Builder/Pro accounts.

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 what the call returns, followed by billing context and the key 'this call is free' note. Three sentences, each earning its place, with no restatement of the name or title.

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 input parameters and no output schema, the description carries the return-content burden, and it does so by listing the fields the agent will get. The account/billing context is sufficient for an agent to decide whether and why to call it.

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 defines zero properties, so there are no parameters to document. The description correctly spends no effort on parameter syntax; a baseline 4 applies for a no-parameter tool.

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 — the signed-in account's prepaid credit — and enumerates exactly what it returns (balance, per-call costs, credit by expiry, recent history, how to add more). This is far more specific than a tautology, though it never names or contrasts with the closest sibling, my_history, so it falls short of the top score.

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?

Usage is only implied: an agent can infer you call this to check remaining credit before making paid calls. There is no explicit 'use this when' statement and no mention of alternatives such as my_history or supply_balance, so the guidance is adequate but not actionable on its own.

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, closed-world, so safety is covered. The description adds genuinely new context beyond them: the 7/30/90/365-day retention tiers by account level and the fact that the call is free, plus the shape of the returned answer record.

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 retention terms, then the usage cue and cost. No filler; every sentence carries distinct information.

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?

There is no output schema, and the description compensates by naming the returned fields, the ordering, and the retention window. For a simple, annotation-covered read with one optional parameter, nothing an agent needs to call it 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 single 'limit' parameter (newest first, default 20) is fully documented in the schema. The description adds 'newest first' ordering context but no further parameter detail, so the baseline 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?

States a specific verb+resource: the signed-in account's own recent questions and the answers shown, newest first. It even enumerates the returned fields (headline, points, caveat, sources), which distinguishes it from generic search siblings like search or search_research.

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 a clear usage cue ('Use it to pick up an earlier line of research'), which frames the retrieval-history scenario. It stops short of naming what it should not be used for or pointing to an alternative (e.g. search_research for new topics), so it is clear context without exclusions.

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 establish the safety profile (read-only, idempotent, non-destructive, closed-world). The description adds genuinely new behavioral context beyond them: the no-match fallback that returns all registered parties, the data provenance ('from every TSE list'), and the temporal boundary for candidate data ('from January 2027'). It does not contradict any 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?

Two sentences, information-dense with no filler, and the no-match fallback is placed at the end where it belongs. It leads with a noun phrase rather than the action, but the content is genuinely earned rather than padded.

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 provided, the description correctly carries the return-value burden by enumerating the profile contents. The single parameter is fully documented in the schema, and the missing pieces are minor (no explicit alternatives), so the definition is largely self-sufficient.

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% for the single 'name' parameter, including examples, so the schema already carries the parameter burden. The description adds no syntax, alias, or format guidance beyond what the schema provides, making the baseline 3 appropriate.

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 (a Guatemalan political party profile) and enumerates exactly what it returns: TSE registration/status, officers, membership history, current deputies, candidates, and news. This is specific and distinguishable from generic siblings like entity_network or entity_timeline, though it never explicitly names a sibling it competes with, keeping it out of 5 territory.

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?

There is no stated when-to-use condition or routing guidance against alternatives such as deputy_record, entity_network, or entity_timeline. The only conditional information is a fallback behavior ('With no match, lists all registered parties'), which describes an outcome rather than prescribing when this tool should be chosen.

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 this is a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds useful context about the bidirectionality and output structure (nodes and links), but doesn't discuss rate limits, data freshness, or other behavioral traits.

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, well-structured sentence that front-loads the core purpose and then details the bidirectional output. It is appropriately sized, though the parenthetical country list is a minor distraction.

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's complexity, annotations, and lack of an output schema, the description provides sufficient context for an agent to understand what the tool does and what it returns. It could be improved by mentioning when to use it versus siblings, but it is largely 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?

Schema description coverage is only 33%—only the 'name' parameter is described. The description does not elaborate on the semantics of 'limit' or 'country', leaving them undocumented outside the schema. Baseline for low coverage is 3 when the description adds no 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 clearly states a verb-resource pair ('buyer ↔ supplier network around one organisation') and specifies the bidirectional scope: for a supplier, the agencies that buy from it; for an agency, its suppliers. It distinguishes itself from the sibling entity_network, which likely covers other entity types, though the difference is not explicit.

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?

Usage is implied—use this to explore procurement relationships for an organisation in the four listed countries. However, there is no explicit guidance on when to prefer this over alternatives like entity_network, find_suppliers, or similar_awards.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety behavior is covered. The description adds the cube's dimensional structure and rollup/group semantics and a link to external query-format docs, which is useful but not rich behavioral disclosure (no pagination, limits, or error behavior).

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 tight sentences with the capability front-loaded and the doc pointers relegated to the end. Slightly dense with two external URLs, but nothing is wasted.

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 complex nested-schema tool with no output schema, the description leans on external links (docs and JSON Schema) rather than explaining the matrix/rows/geojson outputs or constraints. The schema carries most meaning, leaving the description only minimally 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?

Schema description coverage is 80%, so the schema already documents most parameters including geo.in, drill, rollup, time, format and by. The description restates rollups (CA7, SICA8, NTCA) and matrix output without adding syntax or format detail, so the baseline 3 holds.

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 (runs a structured query) and resource (the datosmcp cube with indicators × places × years), plus distinguishing features like regional rollups and matrix output. It references sibling helpers find_indicators and list_places, so an agent can place it, but doesn't explicitly contrast with data-access siblings such as search_data.

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?

Usage is implied rather than stated: the description routes the agent to find_indicators for indicator ids and list_places for geo codes and mentions the query-format spec. There is no explicit when-to-use/when-not or comparison against alternatives like search_data, so an agent must infer the 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?

The annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that a report is sent to a team and what content to include, but it does not explain what happens after submission or any confirmation behavior. With annotations carrying the main behavioral signals, this is adequate but not rich.

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, all front-loaded and purposeful: purpose and report categories first, then field guidance, then usage context. No filler or repetition; every sentence earns its 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?

Given seven parameters, 43% schema coverage, and no output schema, the description supplies the essential context an agent needs: what the tool does, when to use it, and what to include. It could be stronger by clarifying required fields or post-submission behavior, but it is largely complete for a reporting 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 description coverage is only 43%, so the description must compensate. It does map the report kinds to plain language and advises including indicator, place, and period when known, which adds useful guidance beyond the bare enum and parameter names. However, it does not fully document all parameters or explain the required kind/message constraints, leaving gaps.

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 specific verb and resource: 'Sends a report to the datosmcp team.' It then enumerates the reportable conditions (wrong value, missing data, mismatched answer, better source), which distinguishes this tool from the many data-query and search siblings.

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 a clear usage trigger: 'Use when the user asks to report something, or when you find a clear error in a result.' However, it does not state when not to use it, such as for normal data retrieval, which is left to inference from the sibling tool set.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful scope context beyond that: the exact set of supported countries (GT, SV, HN, NI, CR, PA, BZ, DO) and the shape of what is returned. It omits any auth or rate-limit context, so a 4 rather than 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?

A single front-loaded sentence defines the input-to-output transformation with illustrative examples, followed by one short sentence scoping coverage. No filler and no repetition of structured fields.

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?

There is no output schema, so the description correctly carries the return-value burden, naming the code, hierarchy levels, centre coordinates and area. What is missing is behavior around ambiguity or when both text and lat/lon are supplied, and no mention of the 'level' restriction, leaving a modest gap for a five-parameter 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?

With only 40% schema description coverage, the description must compensate, and it partially does: it clarifies that 'text' accepts people's informal spellings and that lat/lon is an alternative input path, which the schema never says. But it never mentions the 'level' parameter or its enum, nor the country filter, leaning on the schema for those.

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 transformation: a colloquial place name or lat/lon becomes an official code plus its hierarchy (country, department, municipality) with centre coordinates and area. This is far more specific than a bare verb+resource. It implies a distinction from search_places/list_places by describing a single canonical resolution, but it never explicitly names or contrasts a sibling tool, so it falls short of a 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 makes clear the two accepted input modes (free-form names like "Xela"/"zona 10", or lat/lon) and the supported country set, which implies usage. However, it offers no when-to-use/when-not guidance versus search_places, list_places, or enrich_place, and no indication of what to do if the answer is ambiguous.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and idempotency profile is fully covered. The description adds useful detail that results include id/title/url and that ids feed 'fetch', but it does not disclose ranking, pagination, or result-count behavior for a search tool.

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 tight sentences: the first front-loads what is searched and what is returned, the second explains the id-to-fetch handoff. Nothing is wasted, though the sentence runs a bit long with the parenthetical enumeration.

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 single-parameter read-only search with annotations covering the safety profile and no output schema, the description covers purpose, result shape (id/title/url), and the follow-up fetch step. It is nearly complete; only pagination/ranking and explicit sibling differentiation 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 description coverage is 100%, with the sole 'query' parameter documented as accepting Spanish or English text plus min/max length. The description adds no syntax or format guidance beyond the schema, so the baseline of 3 is appropriate for a fully documented single parameter.

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 specific verb ('Searches') and resource ('datosmcp for Central American public data'), and enumerates the three result categories (indicators, places, direct answer). It is clear but does not distinguish itself from the many search_* siblings in the toolset, which leaves some risk of wrong-tool selection.

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 says it returns ids that should be passed to 'fetch' for full text, which implies a two-step search-then-fetch workflow. However, there is no explicit when-to-use guidance versus the numerous sibling search tools (search_data, search_places, search_news, find_indicators, list_places, etc.), leaving usage context implied rather than 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?

Annotations already cover the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description needn't restate it. It does add genuine value by disclosing result content — procedural steps and whether a bill became law (decree number) — which annotations cannot convey. It is silent on pagination, result size, or rate limits despite none of that being covered elsewhere.

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?

A single dense sentence that front-loads the resource and its contents before the filter list. Every clause carries information, though the filter enumeration is slightly packed and could be tighter. No boilerplate or restated name/title.

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 usefully sketches the return content (sponsors, committees, steps, decree outcome), which is its main completeness win. However, it omits pagination/limit behavior and the fact that all six parameters are optional (zero required), leaving an agent to infer defaults. Adequate for a 6-param tool but with clear 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 description coverage is only 33%: q and sponsor are documented, while from, to, and limit are bare. The description compensates by mapping filters onto these params, notably clarifying that dates are a filter dimension (explaining from/to) and confirming the words/sponsor/status dimensions. It does not explain the direction or format of from/to or the meaning of limit, keeping it from 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?

Names a specific resource ('Guatemala's Congress bills (iniciativas de ley)') and enumerates what the record contains — sponsors, committees, procedural steps, law outcome. This is clearly distinct from a bare 'search' verb. It stops short of explicitly differentiating itself from close siblings like congress_votes or search_legal, so it lands at 4 rather than 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 'Filter by words, sponsor deputy, status, and dates' clause implies how the tool is driven, which is a weak form of usage guidance. There is no explicit when-to-use, when-not-to-use, or named alternative among the many search_* siblings. Usage is inferable but not 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the lower bar applies. The description adds genuinely useful context by enumerating what comes back — resolved query, rows, nested matrix, gaps, sources, alternative indicators — which is important since no output schema exists. It does not mention pagination, latency, or breadth limits, keeping it short of 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?

Two tightly packed sentences with zero filler: the first defines the tool and its inputs, the second enumerates the response shape. Front-loaded correctly, though the return-value list is dense enough that it could be trimmed slightly.

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 and only two simple parameters, the description carries the burden of explaining returns and does so explicitly, including gaps and alternative indicators. What is missing is routing guidance against sibling data tools, which matters in a 35-tool family.

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 question, in Spanish or English' and 'Restrict to one topic' are already in the schema. The description restates the language support for the question but never mentions the domain filter or when to use it, adding essentially no semantics beyond the structured fields.

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 concrete verb (answers), the input type (a plain-language question in Spanish or English) and the resource (Central American public data), backed by two realistic example queries. It implicitly contrasts with structured-query siblings like query_data, but never names an alternative outright, so the differentiation is inferential rather than explicit.

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 makes the use case clear (natural-language questions, bilingual) and the examples show the expected question shape. However, it gives no when-not guidance and never names query_data, find_indicators, or search as the structured alternatives, leaving routing between the family of data tools to inference.

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 and closed-world, so safety is covered. The description adds real value by disclosing the Spanish-only full-text constraint and the response contents (excerpts, official source URL, archived copy of the original), which matters since no output schema exists.

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?

A single front-loaded sentence that leads with the verb and language constraint, then the scope. It is somewhat run-on in the country enumeration, but nearly every clause adds usable information.

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 7-parameter, output-schema-less search tool the description adequately covers domain, language, geography and return payload, but omits date-range semantics, the 50-result cap, and the kind filter's meaning. Adequate but with clear gaps against the schema's undocumented surface.

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 only 29% (just q and topic are documented), so the description carries the burden for kind, country, from, to and limit. It never mentions date filters, the limit cap, or the enum values explicitly, only loosely implying country and document-type scoping via the coverage list. That leaves most parameters undocumented in both places.

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 ('Full-text search') plus a precise resource set (laws, decrees, regulations, court rulings) and enumerates the covered jurisdictions. An agent can distinguish it from siblings like search_bills or search_news without opening the schema.

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?

Coverage constraints (Spanish-language full text; Costa Rica, El Salvador, Dominican Republic, Nicaragua, Belize, plus Guatemala Congress decrees) imply when the tool applies, but there is no explicit when-to-use/when-not and no named alternative such as search_bills. Usage is inferable but not spelled out.

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 the safe read-only, idempotent, closed-world profile, so the bar is lower. The description adds genuinely useful context beyond annotations: the search corpus is Spanish-language and geographically limited to Guatemala/Central America, and it enumerates the fields returned per item.

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 sentences, front-loaded with the resource and the returned fields, followed by the query/filter/timeline mechanics. Dense and mostly waste-free, though the field enumeration slightly crowds the second 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?

With no output schema, the description helpfully names the returned fields (headline, summary, outlet, section, date), and the annotations carry the safety profile; the Spanish-only and geo scoping are disclosed. The only real gap is the undocumented limit parameter.

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 only 40% (only from and timeline documented), so the description must compensate and largely does: it explains q is Spanish full-text, from/to form a date-range filter, and timeline: true traces an event over time. Only limit is left unexplained in both places.

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 (searches) and a well-scoped resource: Guatemalan and Central American news items, further enumerated as headline, summary, outlet, section and date. The domain is clearly distinct from siblings like search_legal or search_bills, though the description never names an alternative to route the agent.

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 explains capabilities (Spanish full-text, date-range filtering, timeline mode) which implies usage, and gives a condition for timeline: true. However there is no explicit when-to-use/when-not-to-use guidance and no routing against the many sibling search_* tools.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description usefully adds the source aggregation and geographic boundary, but says nothing about rate limits, auth, or how results are ordered/paginated.

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?

One dense but well-formed sentence that front-loads the search action and resource types, then layers in scope, sources, and result content. No filler text.

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 usefully notes the result payload (deadlines, sectors, links to the original notice). For a 6-parameter tool it still leaves parameter behavior (limit, open_only, country code format) partly to the schema, but the overall coverage is solid.

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 50%; the description loosely mirrors 'sectors', 'countries', and opportunity kinds but adds no syntax or defaults beyond the schema. It does not clarify the 'limit' cap or the open_only default behavior, so it only marginally compensates for the coverage gap. Baseline 3 is appropriate.

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 ('Searches') plus the exact resource types (RFPs, tenders, EOIs, grants), the geographic scope (Central America), and the named source corpus (World Bank, IDB, EU TED/Funding & Tenders, Grants.gov). This clearly separates it from siblings like search_news or search_legal without opening any schema.

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 corpus and geography imply the intended use case, but there is no explicit 'use this when…' or exclusion against alternatives such as browse_marketplace or search. An agent must infer the routing decision itself.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld=false), so the bar is lower. The description adds genuine behavioral context beyond the annotations: the data provenance (Overture Maps) and refresh cadence ('refreshed monthly'), which tells the agent about data freshness.

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?

A single dense sentence that is front-loaded with scope and coverage region. It earns its space via the examples and return-field listing, though the packing of many clauses makes it slightly heavy.

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 helpfully enumerates returned fields (address, municipality, phone, website, coordinates, outlets per municipality), compensating appropriately. The main gap is the unexplained 'country' parameter, whose schema has no description either.

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 67% and the schema already documents q, chain, group, and place. The description maps filtering to words/category group/place and mentions chain outposts, adding only marginal meaning; it does not explain the distinction or overlap between the 'place' and 'country' parameters.

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 resource (individual places/businesses) and verb (search) with a concrete coverage area (Central America and the Dominican Republic) and data source (Overture Maps). It clearly says what it returns, but does not differentiate itself from siblings like list_places, resolve_place, or enrich_place, leaving the agent to infer the distinction.

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?

Usage is implied by the enumerated search dimensions (words, category group, place) and examples, but there is no explicit when-to-use statement and no mention of the alternative sibling tools (list_places, resolve_place, enrich_place) that could also apply. The agent must infer the 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral detail absent from annotations: cheapest-first ordering by price per kg/litre/unit, median per store, promotions, and 7/30-day changes. Even though no output schema exists, it discloses the shape of results and the store-page link.

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?

A single dense sentence, but it is front-loaded with the core concept ('Today's online shelf prices in Guatemalan stores') and every clause carries information. Slightly overloaded with retailer and return-format details, yet 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?

With no output schema, the description carries the burden of describing returns and does so adequately (ordering, median, promotions, changes, links). Zero required params and full annotation coverage of safety mean little else is missing, though the optional-parameter interplay (q vs basket) could be clearer.

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 only 50% (country and retailer are undocumented in the schema), so the description must compensate. It partly does: the retailer names (Walmart/Paiz/Despensa Familiar, Cemaco, Elektra) give meaning to the retailer param and the basket examples (arroz, pollo entero, cemento, pilas) reinforce basket. However country and the exact distinction between q and basket remain unaddressed.

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 ('find products', 'online shelf prices'), names the geographic scope (Guatemalan stores) and specific retailers, and clearly distinguishes it from siblings like search_news, trade_by_product, or convert_currency. An agent can tell exactly what this returns without opening the schema.

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 ('find products by words or a household basket item') but never states when to prefer this over alternatives or any exclusions. Usage is inferable but not explicitly guided.

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 and closed-world, so the safety profile is covered. The description adds valuable context beyond that: the search language, the repository coverage scope ('Universidad del Valle de Guatemala so far'), and the exact shape of results – helpful since there is no output schema. It does not mention pagination, result counts, or rate limits.

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?

It is a single front-loaded sentence that is dense but efficient, delivering the corpus, language, coverage caveat and return fields with no filler. The trailing colon list is slightly heavy but every element carries information.

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 does well to name the return fields, which is the main completeness win. However, the five-parameter schema with low coverage leaves the agent guessing about to/limit/institution semantics and about result ordering or count, so it is only partially 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?

Schema description coverage is only 40%, so the description should compensate, but it adds almost nothing about parameters. Three of five parameters (to, limit, institution) are undocumented in both the schema and the description, and even the year filter is only implied by the listed return field 'year', not stated as an input.

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 gives a specific verb (full-text search) and a precise resource (theses, papers and reports from Central American university repositories), and it enumerates the returned fields. This clearly separates it from the numerous search_* siblings like search_news or search_legal, which cover entirely different corpora.

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?

Usage is implied by the domain and the '(Spanish)' qualifier, so an agent can infer it is for Spanish-language academic research, but there is no explicit when-to-use guidance and no alternative search tool is named for routing. With so many sibling search tools, the absence of any exclusion or alternative is a real gap.

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 readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds genuinely new behavioral context: temporal coverage begins in 2023, queries must be in Spanish, and results include computed aggregates (median/min/max, most frequent winners). It does not mention pagination or result-size limits.

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: what it returns, why to use it, how to query. The purpose and payload are front-loaded and nothing is padded.

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 takes on the job of describing returns and does so thoroughly, plus it states temporal and language scope. Minor gaps remain around country selection/default and result limiting, but an agent can call it 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?

Schema description coverage is only 20% (just item_class), so the description must carry the load. It does compensate for q by supplying Spanish query examples and implies the since default (2023 on), but country (GT/HN/DO/PA), limit, and the meaning of item_class codes are left unexplained.

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 (past public-procurement awards since 2023 for an item or service) and enumerates exactly what comes back: winner, agency, date, specification, quantity, unit price, median/min/max unit price and frequent winners. It is clear and concrete, though it never names a sibling (e.g. search_prices) to sharpen the boundary.

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?

"Use it to price an open tender against previous ones" gives a clear selection context, and the instruction to search in Spanish with worked examples is actionable. There are no exclusions or explicit alternatives, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: it discloses that results are assembled from two sources (USDA PSD for balances, UN Comtrade for values/suppliers) and enumerates the derived metrics returned, which is important since there is no output schema.

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?

A single dense sentence front-loads the core output set before the commodity list, and every clause carries information (metrics, sources, coverage) rather than filler. It reads as a run-on, but nothing is redundant enough to cut.

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 and only one documented parameter, the description carries the return-value burden and does so by listing the metrics and their provenance. Gaps remain around temporal range (which years are available) and result granularity, but an agent can form a correct call from what is given.

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 only 33% (only 'product' is documented), so the description must compensate, and it does: it supplies the supported commodity vocabulary and constrains 'country' to Central America, complementing the enum. It does not explain the language parameter's effect on returned text or map the English commodity names to their Spanish equivalents, so the compensation is partial.

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 the resource concretely (supply balance: production, imports, exports, consumption, import share, self-sufficiency, market value, suppliers) and its scope (staple commodity, Central American country), and it names the two underlying sources (USDA PSD, UN Comtrade). It does not explicitly contrast itself with near-neighbors such as trade_by_product, find_suppliers, or search_prices, so overlap must be inferred.

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?

Usage is implied rather than stated: the agent can infer this is for country-level supply/self-sufficiency questions about listed staples, but there is no explicit when-to-use, no when-not-to-use, and no pointer to an alternative tool for adjacent questions like bilateral trade flows or price lookups.

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/closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the upstream source (CEPII BACI), the HS 6-digit granularity, return units (tonnes and US$ per kg), that it covers the latest year plus a yearly trend, and the default-to-top-products fallback.

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?

Delivered as one dense but well-organized sentence that front-loads the resource and dataset before moving to dimensions and product-input formats. Every clause carries information; the example HS codes are the only mildly expendable element but aid disambiguation.

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, 7 parameters, and very low schema coverage, the description carries a heavy burden and mostly meets it — data source, granularity, units, fallback behavior, and input formats are all stated. The missing 'lang' semantics and any pagination/limit behavior are the only real 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 only 14% (only 'q' is documented), so the description must compensate. It does well: it clarifies q/hs accept HS codes or English words with concrete examples, and implicitly covers flow (imports/exports), partner (by partner country), and year (latest year, trend by year). Only 'lang' goes unaddressed, so it falls just short of full coverage.

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+resource+scope: international trade of one Central American country/DR by product at HS 6-digit level, sourced from CEPII BACI. It cleanly distinguishes itself from data siblings like supply_balance or search_data by naming the dataset, granularity, and flow dimension.

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 implied usage guidance by explaining what happens with and without a product ('without a product, the top products') and what dimensions can be requested (partner, year trend, flow). But it never explicitly says when to prefer this over alternatives such as supply_balance or search_data, leaving the routing implicit.

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