MCP Compras.gov.br

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.3.14
Disambiguation4/5
Most tools have clearly distinct purposes, especially in the contract and sanction families. However, there is some overlap among the many list/consult tools for different data sources (e.g., compras_contratacoes_14133_listar vs compras_pncp_contratacoes_publicacao), and between compras_detalhar_preco_material/servico (which explicitly do not return prices) and the actual price research tools. This could cause an agent to select the wrong one for a price look-up task.
Naming Consistency4/5
Tool names follow a mostly consistent pattern: 'compras_<resource>_<action>'. The resource is often singular (contratacoes, orgao, uasg, sancao) but sometimes plural (contratacoes, fornecedores, sancao). Actions like 'listar', 'consultar', 'buscar' are used predictably. Minor inconsistencies, such as 'compras_checar_sancoes_fornecedor' using 'checar' instead of 'consultar', and 'compras_comparar_periodos_contratacoes' using a verb phrase, are rare and do not hinder understanding.
Tool Count3/5
With 94 tools, the server is extensive but well-scoped for its domain of Brazilian public procurement. The count feels slightly high, particularly due to a large number of contract sub-resource tools (e.g., historico, garantias, faturas, ocorrencias) and several 'compras_pncp_*' tools that could potentially be consolidated. However, each tool maps to a distinct upstream endpoint, and the granularity provides flexibility for agents.
Completeness4/5
The tool surface is remarkably complete, covering the full lifecycle of procurement: planning (PCA/PGC), tenders, contracts, ARP (price records), sanctions, and price research. Minor gaps exist, such as the inability to list all contracts of a supplier without knowing the contracting body (documented in compras_perfil_fornecedor_completo), and the lack of a tool to directly update or delete data (which is appropriate for a read-only consulting MCP). The specific workarounds and limitations are well-documented.
Average 4.1/5 across 93 of 94 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the basic action (listing items) and the endpoint. It does not mention read-only nature, pagination behavior (though schema covers it), error handling, required permissions, or any side effects. The description adds minimal behavioral context beyond the function name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short: two sentences—one functional statement and one endpoint path. It is front-loaded with the purpose. No fluff, but it is perhaps too brief given the lack of annotations and the need for more context. Still, it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, an output schema, and many sibling tools, the description is incomplete. It does not explain how to obtain the required id_contratacao (though the schema hints at it), does not describe pagination behavior, and does not distinguish from similar siblings. The tool needs more context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 3 parameters have descriptions), so the baseline is 3. The description does not add any additional parameter meaning beyond what the schema already provides. It mentions the endpoint but not the parameters. No extra context or clarification is given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists items of a specific contract under law 14.133, using 'Lista itens de uma contratação 14.133 específica.' It names the endpoint and resource. However, it does not differentiate from the sibling tool 'compras_contratacoes_14133_itens_listar', which could have a similar scope, reducing clarity slightly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific contract ID, but it gives no guidance on when to use this tool versus alternatives like 'compras_contratacoes_14133_itens_listar' or 'compras_contratacoes_14133_consultar'. There is no mention of prerequisites, when-not-to-use, or conditional context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only mentions the requirement of 'modalidade' and optional filters. There is no information about read-only vs. destructive actions, rate limits, pagination behavior, or error handling. The description does not contradict any annotations (none exist), but it fails to provide essential behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two short sentences. The main purpose is front-loaded, and it immediately mentions the mandatory constraint. Every sentence is informative, though the structure could be improved by separating the required parameter from the optional filters more clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, an output schema, and no annotations, the description is too sparse. It does not explain the output format, pagination (though parameters exist), the meaning of 'legado', or potential interactions between filters. The description lacks completeness for an agent to reliably invoke the tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minimal value: it lists the optional filters and groups 'codigo_item_material' and 'codigo_item_servico' as a combined filter, which is a slight simplification. However, the schema already describes each parameter with 'opcional' and default values. The description does not explain the meaning of required 'modalidade' beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Lista itens de licitações legado' (lists items of legacy biddings). It specifies the endpoint and mentions the required 'modalidade' parameter. However, it does not explicitly differentiate from sibling tools like 'compras_arp_itens_listar' or 'compras_contratos_itens_listar', which also list items but from different contexts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that 'modalidade' is mandatory and lists optional filters, giving a basic usage hint. However, it provides no guidance on when to use this tool versus the many sibling tools, such as when to prefer this over 'compras_legado_licitacoes_listar' (which lists biddings, not items). No exclusion criteria or alternative suggestions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'Cache 1h' (1-hour cache), which is useful behavioral info. However, there are no annotations provided, and the description does not detail other behaviors like rate limiting, data freshness guarantees, query result limits, or what happens with empty results. For a tool querying a government punitive registry, this is under-specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (5 lines), front-loading the tool name and legal reference. Every sentence provides distinct information: endpoint, law reference, purpose, and caching. However, the newline-separated format is slightly disorganized and could be streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no annotations and an output schema, the description is missing key details like what data fields are returned (useful given no output schema visibility), how pagination works (e.g., total results count), or whether the tool supports partial matches on 'nome'. With complexity moderate (3 params) and full schema coverage, a 3 is appropriate—adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add new meaning to the parameters; it only names the tool's purpose. The schema already documents 'cnpj' as CNPJ (14 digits, with/without punctuation), 'nome' as sanctioned name, and 'pagina' as 1-based page. The description adds no nuance (e.g., whether filtering by CNPJ and nome is AND or OR, or if pagination returns all results).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it consults the CNEP (National Registry of Punished Companies) under the Anti-Corruption Law. It identifies the specific resource (punished companies) and the legal framework, distinguishing it from broad search tools. However, it lacks differentiation from other 'sancao' siblings like compras_sancao_ceis, compras_sancao_ceaf, and compras_sancao_cepim, which also deal with sanctions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives like compras_sancao_ceis (which might cover different sanctions/levels). It mentions 'risk of integrity indicator' but doesn't explain selection criteria. There are no when-to-use, prerequisites, or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a 15-minute cache behavior and lists the endpoint, which gives structural insight. However, it does not explicitly state the read-only nature, pagination behavior, error handling, or the shape of results. The cache note adds value but other behavioral traits are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short: one main sentence, one endpoint line, one cache note. The endpoint line is likely unnecessary for an AI agent but not overly verbose. The cache note is a useful behavioral detail. The entire description is front-loaded and efficient, though the endpoint detail could be omitted without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, 3 required, and an output schema, the description is minimal. It does not explain what information the returned items contain, how to use pagination effectively, or how the required parameters identify a specific contract. Given the existence of an output schema, the return structure is assumed documented elsewhere, but the description lacks context for usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; the endpoint line mirrors the required parameters but does not explain their semantics or how they relate (e.g., that they form a composite key). No extra context is provided for 'pagina' or 'tamanho_pagina' beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lista itens de uma contratação no PNCP', which is a specific verb ('Lista') and resource ('itens de uma contratação'). It distinguishes from siblings by specifying 'no PNCP', differentiating it from tools for other procurement systems (e.g., 14133). However, it does not explicitly contrast with similar item-listing tools like compras_contratacoes_14133_itens_por_contratacao or compras_arp_itens_listar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusion criteria for when to prefer this over sibling tools that also list items for contracts. The agent must infer usage solely from the tool name and brief purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only mentions a 15-minute cache, which is a useful trait, but it does not disclose whether the operation is read-only (though listing implies it), rate limits, data freshness guarantees, or any side effects. For a tool with 5 parameters and external API dependency, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences, front-loading the core purpose. The inclusion of the endpoint and cache duration is relevant and efficient. However, it could slightly improve structure by separating the purpose from the technical details, though this is minor. No unnecessary words are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, an output schema, and no annotations, the description is too brief. It does not explain the PNCP context, the meaning of the date range, or how the pagination works (beyond the schema). The sibling tools include many contract-related options, but the description does not help the agent understand when this specific tool is appropriate. The output schema exists, so full return value documentation is not needed, but the description still lacks important contextual clues.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 5 parameters (e.g., 'data_inicial', 'data_final', 'pagina'). The description adds no additional meaning beyond the schema—it does not explain the date range constraint, the 1-based pagination, or the CNPJ filter format. Since the schema already handles documentation, the description neither adds nor detracts value, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists contracts published in PNCP within a period, using a specific verb ('Lista') and resource ('contratos publicados no PNCP'). The mention of 'PNCP' distinguishes it from sibling tools like 'compras_contratos_listar' (likely a different source). The endpoint and cache duration further clarify the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or scenarios where a different tool (e.g., 'compras_pncp_contrato_por_orgao') would be more appropriate. The implied usage (listing contracts by date range) is clear from the required parameters, but the lack of comparative guidance reduces the score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. It only states the listing action and endpoint, but does not mention pagination (though present in schema), read-only nature, rate limits, or authentication requirements. This is insufficient for an agent to understand the tool's side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief with two sentences plus the endpoint, directly stating the main action and a use case. It is efficiently front-loaded and contains no fluff. However, it could be slightly better structured (e.g., using bullet points) to enhance scannability, hence a 4 rather than 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are covered elsewhere. The description explains what the tool lists (items of 14.133 contracts in a period) and gives the endpoint. However, it omits context about pagination behavior, the nature of 'itens' (e.g., what fields are returned), and how the date range filters items. This is adequate for a simple list tool but has clear informational gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning the schema fully documents each parameter. The description adds the context 'incluídos no período', aligning with the date parameters, but does not add meaning beyond what the schema already provides. Baseline for high coverage is 3, and the description does not elevate above that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists items of contracting processes under law 14.133 within a date period, using the verb 'Lista' with the resource 'itens de contratações 14.133'. It also provides the endpoint. While it implicitly differentiates from siblings that list contracts or items per specific contract, it does not explicitly distinguish itself, so it scores 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Útil para descobrir o que foi licitado em uma janela específica' suggests the tool is for discovering bid items in a specific time window. However, it does not mention when to avoid this tool or name alternative tools for different scopes (e.g., items per contract or contract listing). Guidance is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description bears the full burden. It mentions a cache of 1 hour, which is a useful behavioral detail. However, it doesn't disclose whether results are read-only, whether authentication is required, or any rate limits or consequences of use. Minimal but acceptable for a query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (4 lines in Portuguese) and front-loaded with the tool's purpose and endpoint. Every sentence adds value: name, what it queries, endpoint, applicable scope, cache. No wasted words, though could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema is present, description doesn't need to detail returns. The tool is simple (0 required params, 3 optional) and the description covers the core purpose and a notable behavior (cache). Missing context on when to use this specific sanction type vs. others, but adequate for a straightforward lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters have descriptions in the schema. The description does not add any supplementary info beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it consults 'CEPIM — Entidades Privadas Sem Fins Lucrativos Impedidas', specifying the endpoint and applicable context (convênios/termos de fomento com OSCs). However, it doesn't explicitly differentiate from sibling tools that also check sanctions (e.g., compras_sancao_ceis, compras_sancao_cnep), though the specific focus on private non-profits is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs. alternatives like other sanction checks (ceis, cnep, ceaf) or when not to use it. It lacks usage context, prerequisites, or conditions under which this tool excels.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description only states what the tool does; it does not mention pagination behavior (though schema has params), what happens if no results, auth requirements, or any side effects. For a read-only listing tool, this is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the purpose. It is front-loaded and contains no extraneous text. Every part is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (3 parameters, no enums, no nested objects) and the presence of an output schema, the description is minimally complete. It states the core purpose, and the schema covers parameter details. However, it lacks guidance on when to use this tool versus similar siblings, and does not explain the '14.133' context or pagination behavior beyond what is in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 overall description adds no additional meaning beyond the schema; it does not explain relationships between parameters or provide context that the schema lacks. The schema already describes each parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists results of a specific 14.133 contracting. The verb 'Lista' (lists) and resource 'resultados de uma contratação 14.133 específica' are specific, and the required id_contratacao parameter ties it to a single contracting. The name and description distinguish it from siblings like compras_contratacoes_14133_resultados_listar (likely a list of all results) and compras_contratacoes_14133_itens_por_contratacao (items).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as compras_contratacoes_14133_resultados_listar or compras_contratacoes_14133_itens_por_contratacao. The description implies the id_contratacao should come from listar_contratacoes_14133, but no when-not-to-use or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions client-side pagination and a 15-minute cache, which are useful. However, it does not state whether the operation is read-only, if authentication is required, what rate limits apply, or what happens if the contract ID is invalid. The description is too sparse to fully inform an agent about the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, each providing essential information. The first sentence gives the purpose and endpoint, the second adds pagination and caching behavior. No extraneous words. It is front-loaded with the primary action. Every sentence is earned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters and an output schema, the description is minimal. It covers the core purpose and two behavioral notes (cache, pagination type). However, the 'client-side pagination' note is ambiguous given the server-side pagination parameters, and the description does not explain what a publication is or that the output will contain a list. The presence of an output schema partially compensates, but the description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all three parameters (pagina, id_contrato, tamanho_pagina) having descriptions in the schema. The description adds no additional meaning beyond the endpoint path, which links the parameters to the contract ID. The pagination parameters are described in the schema, so the description does not need to compensate. Score is baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists publicações (publications) from the DOU for a specific contract, using the endpoint path. It specifies the resource (publications) and action (list). However, it does not elaborate on what a 'publicação DOU' entails, which slightly reduces clarity for an agent unfamiliar with the domain. The sibling tools include many contract-related endpoints, but none specifically for publications, so differentiation is adequate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Paginação client-side' and 'Cache 15 min', which provide some operational context. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use compras_contrato_publicacoes vs. compras_contratos_consultar). The usage is implied: use it to retrieve publications of a contract. No when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a 15-minute cache and the upstream requirement, which adds useful behavioral context. However, it does not mention whether the tool is read-only, destructive, or any rate limits. The description is moderately transparent but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences, front-loading the purpose and then adding constraints. Each sentence adds value (purpose, upstream requirement, cache). No fluff, but it could be slightly expanded to include pagination context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is incomplete for a tool with 8 parameters and 3 required. It fails to mention pagination parameters (pagina, tamanho_pagina) or how to use them, which are critical for listing operations. The cryptic 'endpoint 2' adds no value. Given the complexity, the description is too sparse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 documents all parameters. The description only adds the upstream constraint, which is already implied by the required fields. It does not provide additional meaning beyond what the schema offers, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists contract items ('Lista itens de contratos'), which is a specific verb+resource. It distinguishes from sibling contract tools like 'compras_contratos_listar' (lists contracts) and 'compras_contratos_consultar' (consult contract). However, it does not explicitly clarify the scope (e.g., per orgão or date range) beyond the input schema, and the 'endpoint 2' reference is cryptic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the upstream requirement for 'codigoOrgao + dataVigenciaInicialMin/Max', which implies the tool is used when these parameters are available. However, it does not provide explicit when-to-use guidance nor mention alternatives among the many sibling tools. The purpose is clear enough to infer usage, but no exclusions or specific contexts are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Como não há anotações fornecidas, a descrição carrega o ônus total de revelar comportamento. Ela esclarece que a ferramenta consulta um endpoint específico e devolve dados de homolgações, mas não detalha efeitos colaterais (é apenas leitura?), requisitos de autenticação, limites de taxa, ou comportamento de paginação (embora parâmetros cubram parte disso). A ausência de anotações impede uma avaliação mais alta, mas a descrição não contradiz campos estruturados.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A descrição é composta por três frases curtas e informativas, cada uma adicionando valor: o que a ferramenta faz, o endpoint associado, e o que devolve/para que serve. Não há repetição ou redundância. A primeira frase já entrega o propósito principal, o que facilita a compreensão rápida pelo agente.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Considerando a complexidade moderada (4 parâmetros, schema rico, schema de saída presente), a descrição cobre o propósito, o endpoint e a utilidade como fonte primária de preços. A existência de schema de saída reduz a necessidade de detalhar retornos. A descrição é suficiente para que um agente entenda o valor da ferramenta, embora detalhes sobre limitações de período ou performance não estejam presentes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
O schema de entrada já cobre 100% dos parâmetros com descrições detalhadas (data_inicial_resultado, data_final_resultado, pagina, tamanho_pagina). A descrição da ferramenta não adiciona novas informações sobre os parâmetros, mas o schema é autossuficiente. Com cobertura total do schema e saída descrita no resumo geral, a descrição agrega valor contextual sem precisar detalhar parâmetros novamente.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
A descrição indica claramente que a ferramenta lista resultados (homologações) de itens 14.133 em um período, especificando o endpoint e os dados devolvidos (fornecedor vencedor, valor adjudicado, quantitativo homologado). Fornece contexto suficiente sobre o que faz, mas não se distingue explicitamente de ferramentas irmãs como compras_contratacoes_14133_resultados_por_contratacao, o que impede a nota máxima.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
A descrição menciona que a ferramenta é 'fonte primária de preço praticado para o ETP', sugerindo uso em estimativas de preço, mas não fornece orientações explícitas sobre quando usar esta ferramenta versus alternativas, nem quando evitá-la. Não há menção a pré-requisitos, limitações ou cenários de exclusão.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does mention the cache duration (1h) and the endpoint used, which gives some behavioral context. However, it does not state that the tool is read-only, idempotent, or whether authentication is required, leaving gaps for an agent assessing safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds distinct information: tool function, endpoint, return structure, and caching behavior. There is no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and full parameter coverage, the description is largely complete. It adds useful context like 'PGCs começam a aparecer a partir de 2020' and cache info. However, it does not clarify how this list tool differs from the CSV variant, leaving a gap in guidance for agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents all parameters. The description adds minimal value beyond the schema—it does not explain parameter relationships, constraints, or usage tips. The baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists items of PGC (Plano de Gestão de Contratações) from the federal government, mentions the endpoint and the fields returned. However, it does not differentiate itself from sibling PGC tools like compras_pgc_listar_csv or compras_pgc_por_catalogo, which could confuse an agent on which tool to choose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not include when-not-to-use suggestions, prerequisites, or contextual cues that would help an agent decide between this and sibling tools like compras_pgc_listar_csv.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions a cache duration of 15 minutes, which is useful behavioral context, but does not disclose other traits such as whether the data is read-only, potential rate limits, or how results are ordered. A score of 3 reflects that it provides some transparency but has gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with only two sentences: one functional statement and one providing the endpoint and cache info. It is front-loaded with the key purpose. The only small deduction is that the endpoint path could be shortened or omitted for better readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the input schema covers all 4 parameters with descriptions, the description is adequate but not rich. It does not explain the return value structure, which is partly covered by the output schema. However, for a list endpoint with moderate complexity, a score of 3 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any additional meaning beyond what the schema already provides for each parameter. The description mentions the endpoint path, which indirectly connects parameters, but this is not substantive extra semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists 'resultados (vencedores)' for a specific item of a contract in PNCP, using a specific verb and resource. It does not explicitly distinguish it from the many sibling tools, but its specificity about item-level results and the endpoint path provide adequate clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when you need to list winners of a specific contract item, but it provides no guidance on when not to use it or alternatives. Given the large number of sibling tools, explicit exclusions would be helpful, but the description is minimally adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It mentions 'Cache de 24h' (24‑hour cache), which is valuable for an agent to know that results may be stale. However, it does not disclose other traits like pagination behavior, rate limits, or whether the operation is read‑only (implied but not explicit). The cache info makes it 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the primary purpose. Every word earns its place. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the description does not need to explain return values. For a simple list operation with optional filtering, the description covers the key aspects: what it lists, optional filter, and cache duration. It could be enhanced by clarifying that CATSER is a service catalog (vs. CATMAT for materials), but that is not essential given the context. Overall, it is complete enough for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 documents all three parameters. The description reiterates the optional group filter ('opcionalmente filtradas por grupo') but adds no additional meaning or usage context beyond the schema. The cache note is about behavior, not parameters. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists CATSER classes with optional filtering by group. The verb 'listar' and resource 'classes' are specific, and the tool name distinguishes it from siblings like 'compras_catser_listar_secoes' and 'compras_catser_consultar'. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where other tools (e.g., listar_secoes, consultar) would be more appropriate, nor does it state prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses two behavioral traits: client-side pagination and a 15-minute cache. These add value beyond the schema, but with no annotations, the description carries the burden for safety and side effects. As a read operation, this is less critical, but the information is minimal and does not cover potential errors or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with the purpose in the first line and behavioral notes in the second. Every sentence provides value, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with an output schema, the description covers the essential purpose and key behaviors. It lacks explicit guidance on when to use it among many similar contract detail tools, but the tool name and description make the use case clear enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add meaning to the parameters beyond what the schema already provides; it merely mentions pagination behavior, which the parameter descriptions already imply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Lista empenhos do contrato' uses a specific verb and resource, clearly identifying the tool's function. The endpoint path further clarifies what it does, and it is easily distinguishable from sibling tools like faturas, garantias, or ocorrências.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description states only the basic functionality without mentioning scenarios, prerequisites, or exclusions relative to other contract-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavioral traits. It mentions client-side pagination (since upstream doesn't paginate) and a 15-minute cache for the full payload. This gives useful but limited insight—it doesn't discuss idempotency, error handling, or rate limits. It doesn't contradict anything because there are no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two lines covering purpose and key technical details (pagination, cache). It avoids unnecessary words. However, the first line could be slightly more descriptive (e.g., specifying that it lists amendments/versions of a contract), but it's still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters (all documented in schema), an output schema (covering return structure), and moderate complexity, the description adequately covers the purpose and key behavioral details (pagination, cache). It doesn't explain the response format in depth, but the output schema likely covers that. The description is complete enough for an agent to select and use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all three parameters have descriptions). The description adds minimal extra meaning—only the cache and pagination note. Since coverage is high, baseline is 3, but the description provides some additional context about how pagination works (client-side) and the cache duration, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Lista aditivos do contrato' clearly states the tool lists contract amendments (aditivos) from the endpoint /api/contrato/{id}/historico. This distinguishes it from sibling tools like compras_contratos_consultar (general contract info) or compras_contrato_empenhos (obligations), but it doesn't explicitly mention it's a contrasting alternative to any specific sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description hints at usage by noting the contract ID parameter and client-side pagination, implying it should be used when you need amendment history for a specific contract. However, there is no explicit guidance on when not to use it or which alternative tools to consider for different scenarios (e.g., if you need contract details rather than amendments).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that pagination is client-side and that there is a 15-minute cache. It does not mention any destructive behavior, authentication requirements, or rate limits. Since no annotations are provided, the description carries the full burden and provides moderate but not exhaustive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three short sentences, each adding distinct information. It front-loads the main purpose and operational details without any redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers the essential aspects: what it does, its importance, pagination behavior, and caching. It does not need to explain return values due to the output schema. Some minor gaps exist (e.g., error conditions), but overall it is quite complete for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage with descriptions for all three parameters. The description adds the note 'Paginação client-side' which provides additional context about how pagination works, though it may be ambiguous. The cache info is unrelated to parameters. The description adds modest value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists occurrences/penalties for a contract, including the API endpoint and a note on its importance as a key indicator of supplier reliability. This uniquely identifies the tool among many contract-related siblings, as it specifically deals with penalties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus the many other contract detail tools (e.g., compras_contrato_historico_aditivos, compras_contrato_garantias). It only mentions its importance as a key indicator, but no explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a 1-hour cache (useful behavioral trait) and states it returns counts and totals. However, it does not mention that the operation is read-only, pagination behavior, or any authentication requirements. Some transparency is provided but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: purpose, endpoint, return content and utility, cache. It is front-loaded with the key action and resource, and every sentence adds value. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and well-documented parameters, the description covers the main purpose, data source, and caching. It is largely complete for a simple aggregate query, though it could mention the pagination behavior or prerequisites for the organ code. The output schema exists, so return details are not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning beyond the schema (e.g., calling codigo_orgao a 'chave da agregação'), but this is largely redundant. Baseline 3 applies as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool aggregates PGC data by category for an organ and year. It uses the verb 'resumo agregado' and specifies the resource (PGC) and scope. However, it does not explicitly distinguish this from sibling list or CSV tools, though the purpose is self-evident from the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the tool is 'útil para diagnóstico rápido do volume planejado', implying a high-level overview use case. It does not provide explicit guidance on when to avoid this tool or compare it to alternatives like compras_pgc_listar for detailed records. Usage is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral transparency. It mentions the endpoint ('Dados Abertos') and cache duration (15 min), which are helpful. However, it does not disclose rate limits, data freshness beyond cache, error behavior (e.g., empty results), or permission requirements. The input schema already documents the 365-day limit, so the description adds limited behavioral insight beyond the cache note.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only four lines: a clear main sentence, endpoint path, use-case note, and cache info. It is front-loaded with the core purpose. While the use-case sentence is somewhat redundant with the first line, there is no wasteful content. Minor improvement could consolidate the use case into the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, output schema present, no nested objects) and the high schema coverage, the description is largely complete. It covers the action, filter, endpoint, target user, and caching. It could briefly mention the difference from other ARP list/query tools to fully contextualize selection, but this is not a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; all parameters (pagina, tamanho_pagina, data_vigencia_final_min/max, codigo_unidade_gerenciadora) are fully described there. The tool description does not add any parameter-specific semantics beyond what the schema already provides. Baseline score is 3, as the description adds no extra value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Lista ARPs cuja vigência termina dentro do intervalo informado,' which clearly states the action (list), the object (ARPs), and the filter (end-of-validity interval). The use case for identifying ARPs near expiration further clarifies intent. This tool is well-distinguished from siblings like compras_arp_listar (likely unfiltered) and compras_arp_buscar_por_objeto (search by keyword).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Permite ao gestor identificar atas próximas do vencimento,' which provides a clear use context. However, it does not explicitly specify when not to use this tool or compare it with alternatives (e.g., compras_arp_listar or compras_contratos_listar_por_fim_vigencia). The endpoint path and cache info are not usage guidelines. Guidance is implied but not explicit enough for optimal selection among 80+ siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It transparently explains the methodology (IQR outlier discard, Tukey), the calculation results (median, mean, quartiles, etc.), cache duration (10 min), and the output readiness for ETP. However, it does not disclose whether the tool is read-only or destructive, nor does it mention any required permissions or side effects. The absence of annotations makes this a 'satisfactory' but not 'excellent' disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three short paragraphs) and front-loaded with the core purpose and methodology. Every sentence adds value: methodology, composition, calculations, and output format. The only minor inefficiency is the mix of Portuguese and English terms (e.g., 'Cache 10 min') but this is not a structural flaw.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, aggregation logic, statistical calculations), the description covers the main behavioral aspects: methodology, composition, cache, and output readiness. An output schema exists, so the description does not need to explain return values. The description is largely complete, though it could mention that the 'uf' parameter is optional and its effect on results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning by clarifying the max_paginas default (5 pages = 2500 contracts) and the periodo_meses default (12 months recommended by IN SEGES/ME 65/2021). However, the description does not elaborate on 'tipo', 'uf', or 'codigo_item_catalogo' beyond what the schema already says. Overall, the description adds marginal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description provides a specific verb ('Agrega preços praticados aplicando metodologia'), clearly identifies the resource (prices for ETP preparation), and explains the composition by aggregating results from two sibling tools ('compras_pesquisar_preco_material' or '_servico'). This distinguishes it well from its siblings, as it focuses on statistical aggregation for ETP, not raw price queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (for ETP price aggregation using IN SEGES/ME 65/2021 methodology) but lacks explicit guidance on when NOT to use it or what alternatives to choose. It references underlying tools but does not clarify when to call those directly instead. The sibling list includes many price-related tools, but no exclusions or conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a 24-hour cache behavior, which is helpful for understanding data freshness. However, it does not mention that the operation is read-only, that pagination is used (though schema covers this), or any rate limits or performance characteristics. The description is minimal but not misleading; cache info adds some value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of three short sentences, each serving a distinct purpose: stating the core action with optional filter, explaining hierarchy with an example, and noting caching. There is no redundant or irrelevant content. The information is front-loaded and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 0 required params, an output schema, and many sibling tools, the description covers the essential purpose and caching behavior. It lacks explicit usage guidelines (when to choose this over sibling tools) but is otherwise sufficient for a listing tool. The output schema fills in return structure details. Minor gap in guidance holds it back from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; all three parameters have clear descriptions in the schema. The tool description adds only the hierarchical context (example of group and class) which reinforces the meaning of codigo_grupo but does not provide new information beyond the schema. Baseline 3 is appropriate since the description offers marginal semantic addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists CATMAT classes (second-level hierarchy) with optional filtering by group. It provides an explicit example (group 71 Mobiliário, class 7110) and distinguishes itself from sibling tools like compras_catmat_listar_grupos (first-level groups) and compras_catser_listar_classes (services). The verb 'Lista' and resource 'classes do CATMAT' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for browsing second-level material categories, but it does not explicitly state when to use this tool versus alternatives. For example, it does not mention that for first-level groups one should use compras_catmat_listar_grupos, or that specific items can be looked up with compras_catmat_consultar. The optional filtering is noted, but no exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description takes on full burden and effectively discloses key behaviors: client-side pagination (implied by 'paginação client-side'), potential for 200+ entries, and a 15-minute cache. This provides valuable context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at three short sentences, each providing distinct information: endpoint, pagination behavior, and caching. No extraneous or repetitive content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and overall tool complexity, the description sufficiently covers key operational aspects. The mention of cache duration and pagination limits offers context not present in the schema, making it reasonably complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides near-complete descriptions for all three parameters (pagina, id_contrato, tamanho_pagina). The description adds no additional parameter-level context beyond what the schema covers, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it lists the financial schedule for a contract, identifying the resource and specific endpoint. It clearly distinguishes this tool from siblings like compras_contratos_listar by focusing on the financial timeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions client-side pagination and cache expiration, giving implicit usage guidance for handling large or repeated data. However, it does not explicitly state when to use this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions a 1-hour cache and the endpoint, which helps set expectations. However, it does not specify whether the tool is read-only (likely safe) or if there are any idempotency or side effects, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three short sentences covering purpose, endpoint, and return data. The first sentence immediately conveys the main action. While the second and third sentences add useful details, the description could potentially be more compact by integrating the endpoint into a single query, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no nested objects, output schema exists), the description covers the essential purpose, input format, and cache behavior. However, it lacks guidance on error cases (e.g., invalid CNPJ/CPF), output structure (though output schema exists), and how to handle the response. It is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (cnpj_cpf) with full schema description coverage (100%). The description adds context by noting the expected format (14 digits for CNPJ, 11 for CPF, with or without punctuation) and confirms the purpose of the parameter. Since schema coverage is 100%, the baseline is 3; the description adds enough additional clarity to warrant a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Consulta cadastro de um fornecedor pelo CNPJ ou CPF.' It identifies the specific action (consult), the resource (supplier registration), and the input method (CNPJ or CPF). It distinguishes itself from sibling tools like compras_fornecedor_listar by specifying a single-query lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for querying a single supplier by document number, but it does not explicitly state when to use this tool versus alternatives (e.g., compras_fornecedor_listar for multiple suppliers). No exclusions or prerequisites (like required permissions) are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only discloses a 1-hour cache and the endpoint. It does not mention whether the operation is read-only, authentication requirements, rate limits, or other side effects. This is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main action, and includes the endpoint, a usage example, and cache info. Every sentence adds value, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 8 optional parameters, 100% schema coverage, and existing output schema, the description provides a good high-level purpose, usage example, and caching behavior. It could explicitly mention that it returns active suppliers by default (as per schema) but is otherwise adequate for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema by reinforcing the usage of porte and CNAE filters in the example, but does not provide new semantic details for any parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists suppliers in Compras.gov.br with structural filters, mentions the specific endpoint, and provides an example use case (levantar MEs com CNAE de TI). This distinguishes it from sibling tools like compras_fornecedor_consultar or compras_fornecedor_cnpj_receita.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use para mapear fornecedores potenciais por porte/CNAE' with an example, providing clear context for when to use this tool. It does not explicitly state when not to use it or mention alternatives, but the context is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden. It discloses the endpoint URL, coverage scope, and a 15-minute cache policy—useful behavioral traits. However, it doesn't mention important details like rate limits, pagination behavior (beyond what schema implies), or whether data is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of three short sentences for the main purpose plus one for context. There is no wasted text. A small deduction because the technical detail about 'Dados Abertos' might be unnecessary for an agent that doesn't need to know alternative data sources.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters (2 required), no output schema, and no annotations, the description is functional but could be more complete. It covers the core use case, but lacks details on expected output format, error handling, or the exact meaning of 'atas' in context. The existence of 80+ sibling tools raises the bar for differentiation, which the description partially meets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no additional parameter meaning beyond what the schema already provides; it doesn't explain the role of 'cnpj_orgao' beyond its schema description or how pagination parameters interact with the cache.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lista atas registradas no PNCP no período (federal + estadual + municipal)', uses a specific verb ('Lista') and resource ('atas'), and distinguishes itself from sibling tools by noting its scope covers all federation levels, unlike Dados Abertos which only covers SISG.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes the tool is broader than alternative data sources ('mais amplo que Dados Abertos (só federal SISG)'), providing a clear when-not scenario. However, it lacks explicit when-to-use guidance relative to other sibling tools like 'compras_arp_listar' which also lists procurement records.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the endpoint path and that it returns the complete header of the contract. It also mentions a 15-minute cache. However, it does not disclose any potential side effects, rate limits, or authentication requirements. The cache note is useful but incomplete for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and to the point at three sentences. It front-loads the purpose, then provides the endpoint and a return value note, and ends with cache info. It is efficient with no wasted words, though slightly more structure could be helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is an output schema (context signal: has output schema: true), the description does not need to explain return values in detail. It still covers the core purpose, parameters, endpoint, and cache. For a simple lookup tool with rich input schema and output schema, this is adequate but could be more complete by noting any access restrictions or common pitfalls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all three parameters with 100% coverage. The description adds the endpoint path showing the parameter order in the URL, which provides context beyond the schema. It does not add significant additional semantics, but with full schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries a specific contract (contratação) using CNPJ, year, and sequential number. The verb 'consulta' is specific and the resource is well-defined. It distinguishes itself from siblings that list contracts by providing a detailed lookup by these three identifiers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly defines when to use this tool: when you need a specific contract given CNPJ, year, and sequential number. It does not explicitly state when not to use it or mention alternative tools, but the three-parameter requirement is clear. Given the large sibling list, explicit alternatives would improve it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It mentions the cache duration (1 hour), which is helpful. The tool is read-only (implied by 'Consulta'), but it does not disclose other traits like rate limits, authentication needs, or response structure. Since an output schema exists, the return format is not a gap, but more behavioral context would raise confidence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: four sentences covering purpose, endpoint, business implication, usage advice, and cache. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter query tool with an output schema, the description provides key context: what the data means, when to use it, and cache behavior. It is slightly lacking in guidance on combining parameters and pagination behavior, but the schema descriptions fill most gaps. Overall, it is sufficiently complete for the agent to understand the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented. The tool description does not add new meaning beyond the schema; e.g., it mentions CNPJ format and textual search, but the schema already covers these. The interaction between parameters (AND/OR) is not explained. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a query ('Consulta') for the CEIS registry of banned and suspended companies. It explains the meaning of the data (cannot contract with public administration). However, it does not differentiate this from sibling tools like compras_sancao_cepim or compras_sancao_cnep, which are other sanction databases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use this tool 'sempre antes de homologar pregões e contratos' (always before approving bids and contracts), giving a clear when-to-use directive. It does not mention when not to use it or provide alternatives like compras_checar_sancoes_fornecedor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly explains the behavioral differences between count mode (fast, one call) and valor_* mode (pagination, slower, truncation). It even names the internal concurrency (4 calls) and cache duration (30 min). Since no annotations were provided, the description properly carries this burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, uses bold for emphasis, and each sentence serves a purpose. It could be slightly more concise by removing the 'Concurrency interna' line which is an implementation detail, but is otherwise efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (7 parameters, 2 modes, pagination) and the presence of an output schema, the description covers key behaviors, modes, limits, and constraints. It does not explain the return value format for count mode versus valor_* mode, but the output schema presumably handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description primarily adds context for the metrica and granularidade parameters (recommending count for trends, explaining bucket sizes). The overall parameter documentation is already complete in the schema, so the description provides marginal but useful nuance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool produces a time series of hiring data (contratações) aggregated by time buckets. However, it does not explicitly differentiate itself from the many sibling tools that also query contracting data, such as compras_contratacoes_14133_listar or compras_indicadores_consolidados, which may have overlapping purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides direct guidance on when to use count vs valor_* modes, including performance implications and page limits. It does not, however, explicitly state when to prefer this tool over siblings like compras_indicadores_por_periodo or compras_contratacoes_14133_listar for time-series queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does well: it discloses the federated data sources, deduplication logic, and importantly warns about latency (60-90s cold cache, <1s warm with Redis). This is a critical behavioral trait. However, it does not mention other potential side effects like rate limits or auth requirements, leaving minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: first paragraph states purpose and composition, second gives use case, third warns about latency. It is front-loaded and efficient. The latency warning is valuable but adds a third paragraph; could be slightly more concise, but overall effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (federated search, deduplication, 5 optional params, output schema exists), the description covers the main aspects: data sources, deduplication key, result count, and latency. It does not mention data freshness or what happens when no matches are found, but these are minor omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description mentions filtering by CATMAT/CATSER and deduplication, which aligns with parameters but adds no new semantic information beyond the schema's own descriptions (e.g., mutual exclusivity is already stated in the schema). No improvement over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool federates two data sources (Dados Abertos and PNCP) to search for similar contracts, explains the composition (homologated results + PNCP publications filtered by CATMAT/CATSER), and distinguishes it from other contract search tools by focusing on similarity and deduplication. It leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a use case ('Insumo para mapear benchmarks de outros órgãos') but does not explicitly state when to use this tool versus alternatives like compras_contratacoes_14133_consultar or compras_pncp_contratacao_por_orgao. The context is clear but lacks exclusions or comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full transparency burden. It discloses a 24-hour cache, which is useful behavioral insight. However, it does not mention that this is a read-only operation, any authentication requirements, or rate limits. The naming implies listing (read) but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using four short sentences to convey purpose, hierarchy context, usage, and caching. It front-loads the main action. Could be slightly more structured, but every sentence adds value and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 optional params, output schema exists), the description is adequately complete. It explains the tool's role in the catalog hierarchy, provides usage guidance, and notes caching. With an output schema, it does not need to describe return values, though a brief mention of what sections contain (e.g., codes) would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so baseline is 3. The description adds no additional meaning to the parameters (pagina, tamanho_pagina) beyond what the schema already provides. It does not explain their format or behavior beyond what is in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists the sections of CATSER, the highest level of the hierarchy. It explicitly distinguishes from sibling tools by explaining that sections are the entry point before drilling down to lower levels, which differentiates it from 'compras_catser_listar_classes' and other hierarchy tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage directive: use this tool to frame a service contracting into a section before descending to lower levels. It does not explicitly state when not to use it or list alternatives, but the context of the hierarchy and sibling names imply when to use other tools. Lacks explicit exclusions for a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adds important behavioral context: it identifies the endpoint URL, describes the data source (Open Data), and mentions a 1-hour cache. This helps the agent understand data freshness and scope. The description does not cover pagination limits or data variability beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, each providing value: tool purpose, endpoint, data type clarification, use case, and caching. The structure is front-loaded with the main action. No unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and 100% parameter coverage, the description provides sufficient context: endpoint, data nature, use case, and cache behavior. It is adequate for an agent to select and use the tool correctly, though more detail on pagination or error handling could push completeness higher.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all four parameters. The description adds context ("ano/mês") and clarifies that omitting month aggregates the year, but this is not significantly beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the tool returns operational metrics of the API (usage metrics like requests, latency, downloads) by period (year/month), distinguishing it from related sibling tools that focus on procurement data. The verb "Retorna" and resource "métricas operacionais" are clear, but the tool name suggests procurement indicators, causing slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states what the tool does not return ("não dados de compras") and provides a usage context ("análise temporal de disponibilidade do upstream"). However, it does not discuss when to use it versus siblings like compras_indicadores_consolidados or alternatives, missing explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool lists data (idempotent read), mentions a 15-minute cache, and specifies the open data endpoint. It also outlines the nature of the returned information (demand level, remaining legal limit). This is sufficient for an agent to understand the tool's behavior without surprises.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences, each earning its place: purpose, endpoint, output context, and caching behavior. It is front-loaded with the core purpose and avoids any redundant or vague language. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters with full schema coverage, an existing output schema, and many siblings, the description is sufficiently complete. It names the required context (ARP, item) indirectly via endpoint and parameter requirements. It could explicitly state that it operates per item, but the schema already captures that. The caching note adds operational awareness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented in the input schema. The description does not add additional meaning beyond what the schema provides (e.g., explaining how 'numero_ata' relates to the item). Baseline 3 is appropriate as the description offers no extra parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lista adesões (caronas) já realizadas a uma ARP', using a specific verb (list) and resource (adesões to ARP). It also provides context about what data is shown (who adhered, quantity, demand level, remaining limit). Among siblings like 'compras_arp_listar' and 'compras_arp_itens_listar', this tool's purpose is distinct and immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing adhesions to a specific ARP item, but does not explicitly state when to use this tool versus alternatives (e.g., 'compras_arp_saldo_item' or 'compras_arp_unidades_item'). No when-not-to-use or explicit alternative names are provided, leaving the agent to infer context from the tool name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'Cache de 24h' (24-hour cache), which reveals a behavioral trait not covered by any annotations (none provided). However, it does not fully disclose potential side effects, error behavior, or whether the tool requires authentication. The disclosure is helpful but incomplete for a data query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: three short sentences covering purpose, output, usage tips, and caching. No wasted words, front-loaded with the core action. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one parameter, high schema coverage, and provides an output schema (context signal indicates has output schema=true). The description covers purpose, usage guidance, and a 24-hour cache disclosure. It adequately explains what the tool does without needing to detail return values (output schema handles that). Minor gap: does not warn if the code might be invalid or not found, but acceptable for a simple lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as the single parameter 'codigo_item' is fully described in the schema (integer, 4-6 digits, example). The description adds no new parameter semantics beyond the schema example, but it does imply that the code must be known beforehand. A baseline of 3 is appropriate since the schema already covers the parameter well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Consulta detalhes de um item CATSER pelo código' (queries details by code), identifies the exact resource (CATSER item), and lists the returned data (name, description, classification, units). It is clearly distinct from its siblings like compras_catser_listar_secoes and compras_catmat_consultar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use this tool: 'Use para confirmar o código antes de pesquisar preços ou contratações similares.' It implies a prerequisite (need to have the code) and suggests it's the right tool before searching prices or similar contracts. It does not explicitly exclude scenarios or mention alternatives, but the context is clear for a lookup tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses that granularity is implicitly yearly ('ano' implícita — soma todo o período em 1 bucket') and that metric 'count' is fast while 'valor_estimado'/'valor_homologado' require paginated mode. However, it does not specify pagination behavior, error conditions, auth requirements, or what happens if periods have no data. Acceptable but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: 6 well-structured short lines. First line states core purpose, second explains it's a wrapper, third defines output, fourth gives use-case examples. Every sentence earns its place. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (handles return value documentation) and 100% parameter schema coverage, the description is relatively complete. It explains the wrapper logic, output structure, and use cases. Could still benefit from noting pagination behavior for value metrics or clarifying timezone handling, but overall adequate for a comparison wrapper.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so schema already documents all 10 parameters. The description adds no specific parameter-level details beyond listing the metric options and implicitly relating periods to use cases. The schema descriptions are already clear, so the description adds marginal value—baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it compares two periods side-by-side for the same modality, defines it as a wrapper over `compras_aggregate_contratacoes_por_periodo` called twice with implicit yearly granularity, and specifies output (totals, delta, percent delta). Distinguishes well from its underlying tool and from other comparison tools like `compras_indicadores_por_periodo`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete use case examples ('Houve antecipação de licitações em Jun/2024...?') that illustrate when to use. Mentions it's a wrapper over another tool, hinting at underlying complexity. Lacks explicit 'when not to use' or comparison to sibling tools like `compras_indicadores_por_periodo`, but the examples and wrapper description give reasonable usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses the upstream dependency, the required parameters and their constraints (e.g., date window), and cache duration (15 min). This is high-value context beyond what the schema conveys. Missing: what happens on error, pagination behavior beyond schema defaults, or whether results are sorted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at three short paragraphs, each serving a distinct purpose: tool purpose, upstream constraints and sibling pointer, and caching. It front-loads the primary action. A slight improvement could be merging the first two lines more tightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (9 parameters, 3 required) and the presence of an output schema, the description efficiently covers the core constraints and important cross-tool references. It is mostly complete for an experienced user, though novices might need more guidance on the meaning of 'upstream' and the structure of the 1-based pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that `codigoOrgao` is mandatory upstream and suggesting `compras_orgao_listar` for discovery, and by warning that `data_vigencia_inicial_min/max` must be ≤ 365 days apart. This enrichment justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lista contratos federais' using the Dados Abertos API, and the non-normative URL path `/modulo-contratos/1` reinforces the specific verb and resource. It is distinct from sibling tools that target sub-records, but could be more explicit about the limitation to upstream API vs. Comprasnet sub-records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly declares the upstream requirements for `codigoOrgao` and the date window ≤ 365 days, and provides a clear alternative for detailed sub-records: 'use `compras_contrato_*` que consulta o Comprasnet'. This offers solid when/alternative guidance, though it does not clarify when NOT to use this tool in favor of listing siblings like `compras_pncp_contratos_listar`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context beyond the schema: the upstream requirement for specific parameters, the ≤365-day window constraint, and a 15-minute cache. However, it does not mention pagination behavior, rate limits, or what happens when no results are found, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences and a line break. The first sentence states the primary function, and the second conveys usage context and constraints. There is no filler; every part earns its place. It is well-structured and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 6 parameters (3 required) and an output schema, the description is reasonably complete. It covers the tool's purpose, usage context, and a key constraint (365-day window). The output schema handles return value details. It could mention pagination behavior explicitly, but the schema's default values for pagina and tamanho_pagina make this mostly self-evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minimal additional meaning: it reiterates the 365-day window (already in the schema for data_vigencia_final_min) and emphasizes the combination of codigo_orgao with the date range. It does not explain parameter formats or edge cases beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Lista contratos com vencimento na janela informada' (lists contracts with expiry in the informed window). It specifies both the resource (contracts) and the scope (by end-of-validity window), distinguishing it from sibling tools like compras_contratos_listar or compras_arp_por_fim_vigencia. The additional phrase 'Inventário do que precisa renovar' clarifies its practical purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Inventário do que precisa renovar' (inventory of what needs renewal) explains when to use this tool. It also states upstream requirements (codigoOrgao + date range). However, it does not explicitly contrast with alternatives or state when not to use it, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds value by disclosing that the upstream requires a single year integer (not a date window) for `dt_ano_aviso`. However, it does not mention pagination behavior, error handling, authentication needs, or any side effects. The output schema exists but is not referenced. The description is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: purpose then endpoint+constraint. Every sentence contributes essential information. It is front-loaded with the main purpose. No wasted words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters and an output schema. The description focuses on the key constraint (year required) and purpose. It does not explain pagination or other parameters, but those are covered in the schema. The output schema exists, so return values are documented. The description is mostly complete for an agent to understand the tool's scope, though it could briefly mention the legacy regime context or typical use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds emphasis that `dt_ano_aviso` is required and must be a year, but this is largely redundant with the schema's description. The description does not add meaning for other parameters. Given high coverage, baseline is 3; the description provides marginal additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists purchases without bidding (dispensa/inexigibilidade) from the legacy regime. It is distinct from sibling tools like 'compras_legado_licitacoes_listar' which list bids, and the name itself differentiates it. The verb 'Lista' and resource 'compras sem licitação' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the upstream requirement for `dt_ano_aviso` as a full year, not a date range, which guides correct usage. It implies the tool is for legacy regime purchases without bidding, but does not explicitly mention when to avoid it or alternatives. The context is clear enough for an agent to infer usage from the tool name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the endpoint and a type constraint, omitting whether the operation is read-only, what happens on missing IDs, or any side effects. For a simple consult endpoint, this is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed sentences: one declaring purpose, one providing the endpoint and constraint. No filler words. Front-loaded with the most critical information. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (which documents return values), the simple single-parameter structure, and the clear endpoint reference, the description is mostly complete. It could mention that the tool is read-only, but overall it covers the essential context for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes id_compra with 100% coverage, but the description adds context: it clarifies the endpoint path and emphasizes that the upstream requires a string, not a numeric id. This extra semantic detail beyond the schema earns a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it consults a legacy bidding process by id_compra, distinguishing it from sibling tools like compras_legado_licitacoes_listar (list) and compras_legado_itens_licitacao_listar (list items). The specific verb 'Consulta' and resource 'licitação legado' leave no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a crucial usage hint: the upstream expects id_compra as a string, not a numeric id. This helps the agent avoid passing the wrong type. While it doesn't explicitly contrast with all sibling tools, it clearly implies use when a specific string id is available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It accurately notes an important upstream parameter naming convention (`min`/`max` vs `inicial`/`final`), which helps avoid confusion. However, it does not disclose pagination behavior, rate limits, or what the output contains, leaving gaps for a listing operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three sentences, each earning its place: purpose, endpoint/naming hint, and historical context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, 100% schema coverage, and an output schema, the description is mostly complete. The endpoint hint and historical context are valuable. However, since there are no annotations, the description could have disclosed more behavioral details (e.g., that results are paginated).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add parameter-level details beyond the schema; it provides a high-level context about date parameters but no additional semantics for the 8 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists RDC (Regime Diferenciado de Contratações) contracts, a specific procurement regime. It also differentiates itself from the many sibling tools by specifying the legacy endpoint and emphasizing residual relevance today.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context (RDC used for mega-events and World Cup) and implies it's a legacy tool with residual relevance, suggesting use only when RDC-specific contracts are needed. However, it does not explicitly state when not to use it or suggest an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return fields and cache behavior (24h), which adds value beyond the schema. However, it does not explicitly state that the operation is read-only, idempotent, or any error conditions, leaving some gaps for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose, a brief list of returned fields, and a cache note. Every sentence is earned, no wasted words, and it is front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description covers the essential aspects: purpose, return fields, and cache duration. It does not discuss error handling or prerequisites, but for a simple query tool this is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'codigo_orgao' already has a description. The tool description adds 'pelo código' (by code) which reinforces the same meaning, but does not add new semantic value beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Consulta' (queries) and identifies the resource as 'órgão específico pelo código' (specific organ by code), clearly distinguishing it from the sibling tool 'compras_orgao_listar' which lists all organs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Cache 24h' and implies usage when a specific organ code is known, but does not explicitly exclude other tools or provide when-not-to-use guidance. The context is clear for the primary use case, but lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the endpoint and contrasts with a consolidated view, implying raw price output. However, it does not mention behavioral traits like pagination, ordering, or any side effects. The output schema exists but is not referenced. Transparency is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences. The first sentence states the purpose, the second provides the endpoint and key usage guidance. No redundant information, front-loaded, and every sentence is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters (1 required) and an output schema, the description is adequate. It explains the main purpose, endpoint, and directs to an alternative for consolidated data. It doesn't cover prerequisites or limitations, but the schema and output schema fill some gaps. Slightly above baseline.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter descriptions are fully provided in the schema. The description adds no additional meaning beyond the schema, e.g., it does not explain that 'codigo_item_catalogo' is the CATSER code or how to find it. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for service purchase prices (CATSER), with a specific verb 'Pesquisa' and resource 'preços praticados em compras de serviço'. It distinguishes from sibling 'compras_pesquisar_preco_material' by specifying service, and contrasts with the consolidated alternative 'compras_pesquisar_precos_para_etp'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when not to use this tool by directing to the alternative 'compras_pesquisar_precos_para_etp' for consolidated statistics. It lacks guidance on when to use other siblings like 'compras_detalhar_preco_servico', but the main alternative is clearly stated, providing good context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the output format (CSV in 'csv' field) and endpoint, but does not mention any behavioral traits such as pagination limits, rate limits, or error handling. For a read-only CSV export, this is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two sentences that front-load the key information (CSV version of sibling tool, endpoint, use case, return format). Every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has only 3 parameters (1 required) and an output schema exists, the description covers the essential use case and format. It could be slightly improved by mentioning the CSV encoding or structure, but it is sufficiently complete for a simple data export tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description adds no additional meaning or context for the parameters (ano, codigo_uasg, codigo_orgao) beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a CSV version of `compras_pgc_listar`, with the same dataset but in spreadsheet format, and specifies the endpoint and return field. It distinguishes itself from the sibling `compras_pgc_listar` by format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it is useful for pasting into ETP or local spreadsheet, implying when CSV output is needed. It references the sibling tool `compras_pgc_listar` as an alternative, but does not explicitly state when not to use or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must shoulder this burden. It mentions cache duration (1h), but lacks details on pagination behavior, rate limits, or what happens if no results. The tool deals with potentially large data; disclosing default pagination (50 per page) and ordering would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences plus a fragment: first sentence states core function, second gives the endpoint for traceability, third provides a concrete use case and cache notice. No redundant or unnecessary words; front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (3 required), an output schema exists, and no annotations, the description covers the main purpose, context usage (ETP, benchmarking), and cache. It does not explain pagination defaults or the result structure, but the output schema likely covers return values, so the description is largely complete for decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents all parameters. The description adds context by referencing CATMAT/CATSER (matching the enum) and the year in the usage example, but does not explain parameter details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'Lista todos os PGCs que incluem determinado item de catálogo', a specific verb (lista) and resource (PGCs por item). It also contrasts with siblings like compras_pgc_listar (general listing) by filtering on catalog item, and provides an example question clarifying the tool's niche.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests when to use the tool via the example question 'Quais órgãos planejaram comprar esse item este ano? Em que quantidade?' and states it is input for ETP and benchmarking. It does not explicitly exclude alternatives or compare to siblings, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are entirely absent, so the description must disclose behavioral traits. It reveals that the 'esfera' filter is applied client-side and notes that '_total_registros' reflects unfiltered totals—key behavior. It also mentions a 15-minute cache. However, it omits important details like whether results are paginated fully, if the endpoint has rate limits, or if it returns all changes within a date range or only a subset, which would be valuable for agents deciding to paginate or cache.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: three short sentences that tell the user exactly what the tool does (list updated contracts), why it's useful (monitoring retifications/republications), and a key behavioral note (client-side filter and cache). Every sentence adds value, no filler. It is well structured with a clear purpose statement, a usage context, and a technical note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (context signal true), the description does not need to explain return values. With 6 parameters (3 required) and a straightforward purpose (listing updated contracts), the description covers the main use case and the client-side filter nuance. It lacks mention of any constraints like maximum date range, which might be important, but overall it provides sufficient completeness for an agent to decide and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 6 parameters have descriptions in the schema), so the baseline is 3. The description adds significant value beyond the schema by providing context: 'esfera' has a note about client-side application and its effect on '_total_registros'; 'codigo_modalidade' lists common codes with examples (1=Leilão Eletrônico, etc.). This extra guidance helps the agent select and fill parameters correctly, raising the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Lista' (lists), the resource 'contratações alteradas' (altered contracts), and the scope 'no período' (in the period). The endpoint and purpose for monitoring (discovering retifications/republications) are explicit, and the tool is well-differentiated from siblings like 'compras_pncp_contratacoes_publicacao' (publications) and 'compras_pncp_contratacao_por_orgao' (by agency), which cover different slices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is useful for monitoring changes (retifications/republications), which implies when to use it—tracking updates over time rather than static data. However, it provides no explicit guidance on when NOT to use it, such as for accessing the latest publication or original contract data, nor does it list alternative tools for those purposes. The mention of client-side filtering hints at a limitation but not a clear exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It discloses the endpoint, cache duration (1 hour), and the filtering behavior. It does not explicitly state that the operation is read-only, nor does it mention authentication requirements, rate limits, or error handling. While the read-only nature can be inferred, more clarity would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: purpose, endpoint reference, and usage example with caching info. Every sentence adds value, and the most important information is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (known from context) and the tool is a filtered list operation, the description covers the core purpose, filter mechanism, and caching. It could mention pagination behavior or state that results are paginated by default, but the schema already provides defaults. The example helps completeness. Minor gaps include lack of authorization or error conditions, but overall sufficient for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds meaning by explaining that 'codigo_classificacao_superior' is a superior classification code and references a table. It also provides usage context (e.g., IT items). However, it does not elaborate on 'ano', 'pagina', or 'tamanho_pagina' beyond what the schema says, so the added semantic value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists PCA items filtered by superior category (classificacao superior). It differentiates from siblings like compras_pncp_pca_listar by specifying the filter and includes an example ('todos os itens de TI planejados para o ano'). The verb 'Lista' and resource 'itens de PCA' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to aggregate procurement plans by superior category, with a concrete example. However, it does not explicitly compare to alternative tools (e.g., compras_pncp_pca_listar for unfiltered lists) or state when not to use it. The context is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does not disclose whether the operation is read-only or destructive, nor does it mention authentication requirements or rate limits. However, it does add context about the cache duration (1 hour) and the endpoint URL, which informs the agent about data freshness. The behavioral transparency is adequate but incomplete, earning a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three sentences covering purpose, endpoint, business context, and cache behavior. Every sentence adds value, and there is no redundancy or filler. This is an exemplary model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters (both optional), a rich output schema (though not detailed in context), and low complexity, the description is nearly complete. It covers the data source, caching, and business context. The only minor gap is lack of explicit statement about the return format (e.g., JSON response structure), but the output schema exists and likely documents that. A 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 2 parameters with 100% description coverage, and the description does not add semantics beyond the schema. The parameter descriptions in the schema are clear ('CNPJ do sancionado (14 dígitos)', 'Página (1-based)'). The description itself does not explain parameter format or usage further. With full schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists leniency agreements ('acordos de leniência') with CGU. It specifies the API endpoint and explains the business relevance: companies with active agreements are under enhanced compliance commitments, useful for risk analysis in high-value contracts. This distinguishes it from sibling tools like `compras_sancao_ceis` (general sanctions list) and `compras_checar_sancoes_fornecedor` (check supplier sanctions), making the purpose specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions that the data is useful for risk analysis in high-value procurement, providing clear context for when to use this tool (e.g., assessing supplier risk). It does not explicitly state when not to use it or mention alternatives among siblings, but the context is sufficient for an agent to understand appropriate scenarios. A 4 is appropriate as it gives clear guidance without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It discloses the endpoint, cache duration (15 min), and that it is from 'Dados Abertos', which implies read-only open data. However, it does not explicitly state read-only behavior, authentication needs, rate limits, or any side effects. The cache info adds value, but overall transparency is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of three sentences, each serving a distinct purpose: listing the output, providing the endpoint, explaining the function, and noting the cache. No redundant or vague language. It is front-loaded with the primary action and efficiently conveys all necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (context signal: has_output_schema=true), the description does not need to detail return values. It covers the tool's purpose, endpoint, cache policy, and parameter distinctions. The mention of 'potenciais caronas' clarifies the output scope. No gaps are evident given the tool's simplicity and the rich schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema by clarifying that 'numero_ata' is distinct from 'numeroControlePncpAta' and suggesting to use the field from other tools. It also reinforces the purpose of the 'unidade_gerenciadora' parameter. This extra context justifies a score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'UGs participantes (potenciais caronas) de um item da ARP', specifying the verb 'Lista', the resource 'UGs participantes', and the scope 'de um item da ARP'. It distinguishes from sibling tools like compras_arp_adesoes_item by adding 'potenciais caronas' (potential vs actual adhesions) and the endpoint reference, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates usage: it 'determina quais unidades podem usar a ata como carona', suggesting it is for checking potential participants before actual adhesion. However, it does not explicitly state when to use this tool versus alternatives (e.g., compras_arp_adesoes_item for actual adhesions), nor does it provide exclusion criteria or prerequisites. The guidance is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It discloses a 24-hour cache and implies a read-only operation ('consulta'), but does not explicitly state safety, rate limits, or authentication requirements. The cache note adds value, but more details could improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three sentences covering purpose, returns, use case, and caching. Every sentence earns its place with no extraneous information. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single required parameter, presence of an output schema, and clear description of input, output fields, caching, and use case, the tool definition is complete. The description adds value beyond structured fields without being verbose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter already well-documented (integer, 4-8 digits, example). The description adds only 'pelo código', which is redundant. With high schema coverage, the description does not need to add much, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('consulta detalhes') and the resource ('item CATMAT específico pelo código'). It lists the fields returned and provides a use case (confirm code before price research or listing similar contracts), clearly distinguishing it from sibling search/list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description recommends using this tool to confirm the code before price research or listing similar contracts, giving clear context. It does not explicitly exclude other scenarios or name sibling alternatives, but the use-case guidance is specific and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey all important behaviors. It does so by disclosing three key behavioral traits: CPF masking for LGPD compliance ('123.***.***-45'), client-side pagination (implying the API returns all records, and the parameters control local slicing), and a 15-minute cache. These go beyond simply naming the tool's function and provide critical operational context, earning a score of 4. The only gap is a lack of explicit mention that this is a read-only operation, which is strongly implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: three short lines deliver the purpose, endpoint, and three critical behavioral details. Every sentence earns its place with no wasted words. Information is front-loaded with the primary function, followed by essential technical constraints. This is a model of efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of this tool (3 parameters, 1 required, simple scalar types), the description provides complete context for an agent to use it effectively. An output schema exists, so return format documentation is unnecessary. The description covers purpose, endpoint, data masking, pagination behavior, and caching. No significant gaps remain for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning the input schema already documents all parameters (id_contrato, pagina, tamanho_pagina) with descriptions. The main description adds no new parameter-level information beyond the endpoint path and the pagination mention ('Paginação client-side'), which aligns with the parameter descriptions. The description does not add value for individual parameters, so scoring is at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the function: list contract managers/officials (fiscais/gestores) for a specific contract via the /api/contrato/{id}/responsaveis endpoint. The verb 'Lista' combined with the resource 'fiscais/gestores' and the explicit endpoint path provides high specificity. This purpose is well-distinguished from sibling tools, which focus on other contract details (items, invoices, amendments) or entirely different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the core usage context: it requires a contract ID (id_contrato). It does not, however, explicitly state when to use this tool versus alternatives like compras_contratos_consultar, compras_contrato_garantias, or compras_contrato_ocorrencias. There is no guidance on prerequisites (e.g., the contract must exist) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full behavioral disclosure. It states the tool returns specific metrics, provides the endpoint, and mentions a 1-hour cache. It does not discuss authentication, rate limits, or pagination behavior beyond schema parameters, but for a read-only diagnostic tool the disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: four sentences covering purpose, endpoint, return fields, usage context, and caching. Every sentence contributes meaningfully with no redundancy or filler. The structure is logical and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers return metrics, usage guidance, and cache, and the output schema exists. However, it fails to define the time period for the 'período' mentioned (e.g., is it fixed, latest, custom?). This ambiguity about the data scope is a notable gap for a tool returning consolidated metrics over a period.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (pagina, tamanho_pagina) already well-described in the schema. The tool description adds no additional semantic value or context about how these parameters affect results, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns consolidated operational metrics (total services, requests, success rate, latency, download volumes) from the Dados Abertos API. It distinguishes itself from public market indicators by explicitly stating what it is NOT for, which helps differentiate among the many indicator-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the tool is for diagnosis/observability and explicitly warns against using it for public market indicators. However, it does not compare with the sibling 'compras_indicadores_por_periodo' or clarify when to choose one over the other, leaving some usage ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly states it is a query (not a mutation) and notes the 15-minute cache, which helps agents understand latency and data freshness. No contradictions or destructive hints are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, covering purpose, endpoint, and cache policy without fluff. It is front-loaded but could be slightly more structured (e.g., separating purpose from technical details).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and parameters are fully documented, the description adequately covers the tool's behavior. The 15-minute cache note adds important context for repeated queries. However, it could mention what happens with missing data (e.g., 404) or rate limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by mapping parameters to the endpoint path ('/v1/orgaos/{cnpj}/contratos/{ano}/{sequencial}'), clarifying how they relate to the API URL structure. This is useful for agents to understand the request format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Consulta') and resource ('contrato específico') and clearly distinguishes itself from sibling tools by mentioning the endpoint and cache behavior. It directly tells the agent it retrieves a single contract, not a list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the endpoint path and cache duration, implying use by CNPJ, year, and sequential number. However, it lacks explicit guidance on when to use this tool versus alternatives like 'compras_pncp_contratos_listar' or 'compras_contratos_consultar', and no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must self-disclose behavior. It mentions the endpoint, a 1-hour cache, and the action of listing updated PCAs. However, it does not state output format details, rate limits, or required authentication. The cache note is helpful for an agent to understand data freshness. A 4 is appropriate because it covers key behavioral aspects (cache, endpoint) without being exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact with three sentences: the core function, the endpoint, and a hint about cache and monitoring use. Each sentence adds value and is front-loaded. The second and third sentences provide useful context without redundancy. It loses one point for being slightly terse about the monitoring use case but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown but flagged as present), the description does not need to detail return values. The input schema is fully covered by annotations. The description sufficiently explains the tool's purpose and use case. However, it lacks guidance on pagination behavior or how to interpret the results (e.g., what fields are in a PCA). Still, for a listing tool with a known output schema, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any extra parameter guidance beyond defining the tool's overall scope. All parameter details (formats, defaults, constraints like 30-day window) are already present in the schema. The description repeats none of these, so it adds no value above the schema. Hence a score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists PCAs (Plano de Contratações Anual) updated within a period, specifying the endpoint and its utility for monitoring which agencies have recently revised their PCA. The verb 'Lista' combines with resource 'PCAs atualizados' and context 'num período' to make the tool's function explicit. Among siblings like 'compras_pncp_pca_listar' and 'compras_pncp_pca_por_usuario', this one is uniquely identified as the update-fetching variant, effectively distinguishing it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says it is 'Útil para monitoramento: descobrir quais órgãos revisaram seu PCA recentemente', indicating a monitoring use case. It does not, however, specify when NOT to use it or suggest alternative tools for other PCA lookups (like listing all PCAs or filtering by user). With the sibling 'compras_pncp_pca_listar' present, an explicit exclusion would be beneficial, but the context is clear enough for an agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly discloses the upstream requirements (date window ≤365 days), the external endpoint, and the 15-minute cache. It does not explicitly state read-only behavior, but the context 'lista' implies a query operation. Additional behavioral details like rate limits or pagination behavior are not covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is terse and informative. Three sentences: first explains core function and validity window, second adds endpoint and constraint, third mentions optional filters and caching. No filler or redundant phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 8 parameters (2 required), 100% schema coverage, and presence of an output schema, the description provides a concise but sufficient overview. It covers the critical date constraint and caching behavior. The pagination parameters ('pagina', 'tamanho_pagina') are not discussed, but these are common and the schema descriptions address them. Slightly more guidance on pagination defaults would push completeness to 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description briefly mentions optional filters for localizing items but does not elaborate on any parameter beyond the date constraint and the endpoint context. The schema already documents each parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists ARP items within a specific validity window. It mentions the endpoint, data source, and constraints (365-day window). This distinguishes it from sibling tools that list ARPs, contracts, or other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (within the validity window with 365-day limit) and mentions optional filters for locating specific items. It does not, however, provide explicit guidance on when not to use this tool or contrast it with alternative ARP-item tools among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are not provided, so the description must cover behavioral traits. It discloses the 365-day window constraint and that the endpoint is from 'Dados Abertos' (implying public data), and mentions a 15-minute cache. However, it does not state whether this is a read-only safe operation, what the upstream rate limits or response format are, or whether results are sorted. Given no annotations, this is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, focused sentences. The first states the core purpose, the second adds technical context about the upstream, and the third provides an actionable alternative. No wasted words. Slightly dense but efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (context signals say true) and 100% schema coverage on parameters, the description's additional details (upstream endpoint, window constraint, cache, sibling) make it complete enough for an agent to decide and invoke this tool correctly. No obvious gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description mentions the window constraint but does not add new semantics beyond the schema's field descriptions, which already label 'data_vigencia_inicial_min/max' with their date format and obligation. The description is redundant with the schema on parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lista') and resource ('Atas de Registro de Preço (ARPs)'), clearly scoping the operation to listing by 'janela de início de vigência'. It also explicitly references a sibling tool 'compras_arp_por_fim_vigencia' with a different purpose, distinguishing this tool from that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the upstream requires a 'dataVigenciaInicialMin/Max' window of ≤ 365 days, and directly tells when to use an alternative: 'Para listar atas próximas do vencimento, use compras_arp_por_fim_vigencia.' This provides clear when-to-use and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses behavioral traits: client-side pagination, 15-minute cache, and a critical LGPD notice about the `infcomplementar` field potentially containing unstructured personal data (server name + SIAPE number) that is not masked. This is valuable beyond what schema/enum covers. It does not mention if it is read-only or destructive, but the action is a LIST, so read-only is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: one line for the endpoint and pagination, one line for cache, and one line for the LGPD warning. Every sentence adds unique, non-redundant information. No fluff or repetition. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (though not shown here) and 3 well-documented parameters, the description covers the most important behavioral aspects: pagination, caching, and data sensitivity. It does not explain the return structure (but output schema handles that) or error conditions. For a listing tool, this is quite complete. A minor gap is no mention of rate limits or authentication, but those may be system-wide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all three parameters have descriptions), so baseline is 3. The description does not add per-parameter details beyond schema, but it does add context about client-side pagination and the data sensitivity of the results, which indirectly informs how parameters should be used (e.g., paginate efficiently, be cautious with `infcomplementar`). This elevates the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists invoices/faturas for a specific contract, with the endpoint path `/api/contrato/{id}/faturas`. It is specific about the resource (contract invoices) and the action (list), and among the many sibling tools related to contracts (e.g., `compras_contratos_listar`, `compras_contratos_consultar`, `compras_contrato_empenhos`), its purpose is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions client-side pagination and cache, but does not explicitly state when to use this tool versus alternatives like `compras_contrato_empenhos` or `compras_contratos_consultar`. It provides no guidance on prerequisites (e.g., need the contract ID) or conditions that make this tool appropriate. The usage context is implied but not contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It clearly states two key traits: 'Paginação client-side' (client-side pagination) and 'Cache 15 min' (15-minute cache). This informs the agent that pagination is handled locally, not via server parameters, and that data may be stale for up to 15 minutes. For a read-only list tool, this is substantially transparent. No contradictions with annotations (none exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two lines covering purpose, endpoint, pagination behavior, and caching. Every sentence provides essential information with no redundancy. It front-loads the core purpose in the first line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity is low (3 parameters, 1 required, simple output schema likely), the description is sufficiently complete. It covers purpose, endpoint, pagination, and caching. The output schema exists but isn't detailed; the description doesn't need to explain return values. A slight deduction for not mentioning that the guarantees are returned as a list or any filtering details beyond the contract ID, but the endpoint hint compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The schema already documents each parameter (id_contrato, pagina, tamanho_pagina) with types, defaults, descriptions, and constraints (max 500 for tamanho_pagina). The description adds the endpoint context (e.g., that id_contrato is used in the URL path) and the crucial 'client-side pagination' behavior, which clarifies that pagina and tamanho_pagina parameters are for local filtering, not server requests. This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The tool name 'compras_contrato_garantias' and description 'Lista garantias contratuais (/api/contrato/{id}/garantias)' clearly indicate it lists contractual guarantees for a specific contract. The verb 'Lista' (lists) and resource 'garantias contratuais' (contract guarantees) are precise, and the endpoint path further clarifies the scope. This distinguishes it well from siblings like 'compras_contrato_faturas' (invoices) and 'compras_contrato_ocorrencias' (occurrences).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly states usage via the endpoint path: to list guarantees for a contract with a specific ID. It mentions 'Paginação client-side' indicating client-side pagination behavior, which hints at when to use pagination parameters. However, there is no explicit guidance on when to prefer this tool over alternatives like 'compras_contratos_itens_listar' or 'compras_contrato_empenhos', nor any 'when not to use' scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are not provided, so the description carries the full burden. It discloses the endpoint, cache behavior (1h), and that it returns impeded suppliers based on SICAF sanctions. It does not mention rate limits, authentication needs, or what happens if no items are provided or if an item code is invalid. The behavioral scope is acceptable but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, focused sentences covering purpose, endpoint, business reason, and caching. Each sentence adds value without repetition or fluff. Perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a full output schema (context signal says 'Has output schema: true'), so the description doesn't need to detail return values. Parameter coverage is complete via schema. The description covers when to use, cache, and business purpose. It could mention that both parameters are optional (already in schema) and warn that providing both yields a combined result, but this is minor. Overall, quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes both parameters. The description adds no extra semantic detail about the parameters beyond what the schema provides. However, the schema's descriptions are clear (list of CATMAT/CATSER codes, can be used together). Given high coverage, baseline is 3, but the description reinforces the business context and shows cache behavior, making it slightly more helpful—hence 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool checks for supplier impediments on a list of CATMAT/CATSER items, with explicit references to the specific endpoint and use case (before homologating electronic auctions). It distinguishes itself from siblings that deal with sanctions but not by item list (e.g., compras_checar_sancoes_fornecedor).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Essencial antes de homologar pregões eletrônicos'), implying the critical context. However, it does not explicitly say when NOT to use it or mention alternatives among the many sister tools (e.g., compras_checar_sancoes_fornecedor for checking by supplier, not items). A clear exclusion would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the upstream bug and the parameter removal, which is good transparency. However, it does not explicitly state that this is a read-only operation or mention authentication requirements, rate limits, or pagination behavior beyond what the schema implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and efficient: three sentences covering purpose, endpoint, bug, and workaround. No extraneous information. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the main usage context (legacy regime, bug, workaround) and the endpoint. With an output schema present, the description does not need to detail return values. It could briefly mention pagination (since the schema has pagination parameters), but the schema already describes those. Overall, it provides sufficient context for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by explaining why the 'uasg' parameter is missing (due to a bug) and providing a workaround. It also clarifies that the date parameters are required upstream, reinforcing the schema's required flag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists tenders from the legacy regime (Law 8.666/93), with a specific endpoint. The purpose is distinct from sibling tools like 'compras_legado_licitacao_consultar' (which likely fetches a single tender) and tools for the newer regime (Lei 14.133).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool (legacy regime) and a critical caveat: the 'uasg' filter is broken and removed, so the agent must list all results and filter client-side if needed. No explicit comparison to other listing tools, but the bug workaround is valuable for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description rightly carries full behavioral disclosure weight. It openly states the 15-minute cache duration and that the 'esfera' filter is client-side, which prevents misinterpretation of results. It also implies read-only behavior by describing listing and mapeamento. The only minor gap is that it doesn't explicitly state that it's read-only or non-destructive, but given the context, this is still strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at only three short sentences and a cache note. It front-loads the core purpose and endpoint, then adds high-value usage context and a critical behavioral note about client-side filtering. No word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, 2 required, output schema present), the description provides essential usage context and behavioral notes (client-side filter, cache). The presence of an output schema reduces the need to describe return values. The only missing element is an explicit mention that the tool is read-only (safe), but that is implied by the listing nature. Overall, it covers the key gaps well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds some value by noting that 'esfera' is client-side and that '_total_registros' reflects unfiltered total, which is not in the schema. However, it does not add meaning to other parameters beyond what the schema already provides (e.g., 'codigo_modalidade' merely references another input schema). Hence a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Lista') and resource ('contratações com prazo de proposta aberto no PNCP'), which uniquely identifies this tool among many similar contracting tools. It also provides the endpoint path and describes useful use cases for both suppliers and analysts, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says the tool is for mapping open proposal opportunities and identifying ongoing contracts, giving clear context. It mentions the optional 'esfera' filter is applied client-side, which is an important usage caveat. However, it does not explicitly state when to prefer this tool over alternatives (e.g., compras_pncp_contratacoes_publicacao or compras_pncp_contratacoes_atualizacao), so it's slightly below a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It discloses that the tool is local (does not call upstream), sourced from the official PNCP table, and warns about the two different code tables in circulation, including the None case for unavailable modalities. This goes beyond basic expectations and provides useful context for correct interpretation of results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line summary followed by a source note and a clearly marked ATENÇÃO block with bullet points. It is slightly longer than minimal but every sentence serves a purpose, especially the critical warning about the two code systems.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters and an output schema exists (though not shown), the description covers the necessary context: it explains the local nature, the official source, and the relationship to a sibling tool. It effectively disambiguates the modality codes without needing to describe return types, making it sufficiently complete for a reference lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per the rubric baseline is 4. Although there is no parameter semantics to explain, the description adds value by clarifying the meaning of the output codes and the field `equivalente_dados_abertos`, which helps understand the data returned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the tool as a 'Cheat sheet local' for PNCP contracting modality codes, clearly stating the resource (modality codes) and its scope (local, official PNCP table). It distinguishes itself from sibling tools by contrasting the PNCP code system with the Dados Abertos/SIASG enumeration, though it lacks an explicit action verb like 'list' or 'retrieve'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it states that `codigo` here is used in all `compras_pncp_*` tools and in `modalidadeIdPncp`, and it names the alternative endpoint (`compras_contratacoes_14133_listar`) with a different enum, including the mapping field `equivalente_dados_abertos`. This gives clear when-to-use and when-to-use-other guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'Cache 1h', which adds useful caching behavior beyond the schema. No annotations are provided, so there is no contradiction. However, it does not disclose the return format, pagination limit, or any rate limiting or authentication requirements. The description adds some transparency but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three sentences covering purpose, differentiation, key parameter constraint, and cache behavior. Every sentence adds distinct value without redundancy. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a list operation with 5 parameters, an output schema exists, and schema coverage is 100%, the description is quite complete. It covers the essential differentiator from PGC, required parameter guidance, and cache policy. Minor gaps include missing explanation of pagination behavior or default sorting order, but these are not critical for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that 'codigo_classificacao_superior' is a mandatory upstream parameter and provides guidance on how to get its value (via compras_catmat_listar_grupos or compras_catser_listar_secoes). This extra context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lista PCAs (Planos Anuais de Contratações) no PNCP', identifying the specific verb (list) and resource (PCAs). It distinguishes itself from siblings like compras_pgc_listar by explicitly mentioning the different legal framework (Lei 14.133) and coverage (federais + estaduais + municipais).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that 'Diferente do PGC, o PCA da Lei 14.133 cobre federais + estaduais + municipais' which helps differentiate from PGC tools. It also mentions a required filter ('codigo_classificacao_superior é obrigatório no upstream') and hints at alternatives (CATMAT groups, CATSER sections) but does not explicitly list when-not-to-use or provide comprehensive sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries the full burden. It discloses a 24h cache and that groups change rarely, giving the agent awareness of staleness. It also states the approximate count (~79 groups). The verb 'listar' implies a read-only operation, so no destructive behavior. However, it does not mention authentication requirements, rate limits, or details about the output format (but an 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: three short paragraphs covering purpose, hierarchy context, and caching behavior. Every sentence adds value. There is no redundant or wasted verbiage. The main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with two parameters and an existing output schema, the description is complete. It explains what is listed, the hierarchy, the caching policy, and the approximate number of results. All necessary context for the agent to use the tool correctly is present, and the output schema compensates for return value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema for the two pagination parameters. It does not discuss default values, maximums, or format expectations. The agent must rely solely on the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lista os grupos do CATMAT (Catálogo de Materiais)' with a specific verb (list) and resource (groups). It explains that groups are the highest hierarchy level and provides an example. This distinguishes the tool from siblings like compras_catmat_listar_classes (next level down) and compras_catmat_buscar (search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use: 'Use esta tool para enquadrar a contratação no grupo correto antes de descer para classes/PDM/itens'. This gives clear context for the tool's place in a workflow. It also notes the 24h cache, indicating real-time updates are unnecessary. However, it does not explicitly exclude alternatives like compras_catmat_buscar or mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description covers key behavioral traits: parallel calls to multiple sources, return type (boolean + list), error condition (ComprasAuthError if API key missing), and caching (10 min). It does not discuss rate limits or idempotency, but for a read-like operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences: purpose, composition, return, error+usage+cache. Every sentence adds value and is front-loaded with critical information. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the tool has a single parameter, the description covers all essential aspects: consolidation logic, error handling, caching, and recommended use case. It is fully adequate for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the single parameter 'cnpj'. The tool description adds no additional parameter semantics beyond the schema, meeting the baseline expectation of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it consolidates sanctions from multiple sources (CEIS, CNEP, CEPIM, leniência, impedimentos) and returns a boolean verdict plus a consolidated list. This distinctly differentiates it from sibling tools like compras_sancao_ceis or compras_sancao_cnep, which cover only individual lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Sempre use antes de homologar pregões/contratos' (always use before finalizing bids/contracts), providing clear when-to-use context. It does not explicitly mention when not to use or alternatives, but the consolidation purpose implies when the granular sibling tools would be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a 15-minute cache, the return of both Dados Abertos and PNCP modalidade fields, and recommends using `modalidadeNome` for readability. It also warns about the non-standard code table. This is strong behavioral disclosure beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief purpose statement, endpoint reference, coverage scope, and a bolded semantic warning. It is front-loaded and efficient, though the warning could be integrated into a single sentence. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, output schema exists), the description covers the essential aspects: scope, caching, modalidade nuance, and alternative tool. It does not explain pagination behavior or error handling, but these are partially covered by the schema and output schema. Overall, it is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant value for `codigo_modalidade_dados_abertos` by providing equivalent codes, clarifying it uses the Dados Abertos/SIASG table, and warning against the PNCP cheat sheet. This goes well beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists contracts under Lei 14.133 from PNCP via Dados Abertos, specifying the endpoint and coverage of modalities. It explicitly distinguishes from the sibling tool `compras_pncp_contratacoes_publicacao` by warning about the different modalidade code table, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs. the alternative `compras_pncp_contratacoes_publicacao` for modalidade filtering, and explains the semantic difference in the `codigo_modalidade_dados_abertos` parameter. It gives clear context but does not exhaustively cover all exclude conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It transparently discloses a known upstream bug (HTTP 400, Hibernate error) and the removal of documented filters, which is crucial behavioral information. It also indicates client-side filtering is needed for UASG/orgão. This is exceptional transparency for a tool with no annotations, though it doesn't detail pagination limits or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose in the first line. The second paragraph details the bug and workaround efficiently. Every sentence contributes useful information. Minor improvement: could merge the purpose and endpoint into one sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters (100% schema coverage), an output schema, and no annotations, the description is fairly complete for a list operation. It covers the core purpose, a critical bug, and a workaround. However, it does not confirm that output is paginated (implied by `pagina` and `tamanho_pagina`) or describe the return structure beyond mentioning `coUasg`/`coOrgao` fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining why two parameters (co_uasg, co_orgao) are absent (upstream bug), which is a meaningful addition beyond the schema. However, the description itself does not elaborate on each parameter's semantics, but the schema already fully covers them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'pregões eletrônicos do regime legado' (electronic bidding notices from the legacy system) and provides the specific endpoint. The verb 'listar' (list) combined with the resource 'pregões eletrônicos' distinguishes it from siblings like 'compras_legado_licitacoes_listar' (list bids) and 'compras_legado_rdc_listar' (list RDC). The scope is precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly documents a critical bug with the `co_uasg` and `co_orgao` filters, stating they were removed due to Hibernate errors, and provides a workaround: call without filters and filter client-side. This tells the agent when NOT to use those filters and how to achieve the same result. However, it does not compare against specific sibling tools or advise when to use this tool over others for legacy procurement queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns the content of PromptMessage[0], describes error handling (returns '_erro' with diagnostic instead of exception), and specifies the return structure. Though it does not mention side effects or idempotency, the description covers the essential behavioral traits for a prompt-rendering tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at about five sentences, with the primary purpose stated first. Every sentence adds value: purpose, return content explanation, return structure, and error handling. No superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (rendering a prompt) and the presence of an output schema described in the description, the information is complete. It covers what the tool does, how to use it (including referencing the sibling listing tool), the return format, and error behavior. The sibling list is large, but the description provides sufficient context for an agent to decide when to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description does not add additional meaning beyond the schema's parameter descriptions. The schema already provides examples, references to list_prompts, and type constraints. The description's role is fulfilled by the schema, so no extra credit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Renderiza um MCP Prompt e devolve o texto pronto.' This is a specific verb+resource pair. It further explains the returned text is a script that guides the LLM to call other tools, distinguishing it from data-retrieval tools. The sibling list includes compras_listar_prompts, but this tool's purpose of rendering a specific prompt is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that after obtaining the prompt text, the LLM typically follows its instructions to call other tools. It also advises using compras_listar_prompts to discover available prompt names. However, it does not explicitly state when not to use this tool or list alternatives, leaving a minor gap in exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations were provided, so the description carries full burden. It discloses the upstream endpoint, the one-row-per-combination structure, the non-duplicative nature of multiple rows per numeroItem, the inclusion of a resumo_por_item aggregated dict, a cache duration of 15 minutes, and a mention of a bug fix. This is comprehensive behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bolded key terms, bullet points, and clear sections. It is informative without being overly verbose. Each sentence adds value, including the bug fix note and cache info. Slightly more concise than typical, but still thorough.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to detail return values. It explains the data model, aggregation, critical usage scenario, and cache behavior. This provides complete context for an agent to use the tool correctly. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters documented. The description does not add significant extra meaning beyond the schema—it mentions the required parameters but doesn't elaborate on their semantics or usage. The baseline of 3 is appropriate as the schema already handles parameter description adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the balance (quantidade ainda disponível) per item of an ARP. It specifies the endpoint and distinguishes from sibling ARP tools by focusing on 'saldo', which is a distinct concept from listing, consulting, or other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context: 'Crítico para adesão: a ata pode estar vigente mas com saldo zerado. Sem saldo, não há como aderir.' This tells when to use the tool. It also explains the data structure and cache behavior. However, it does not directly name alternative tools for different scenarios, though the sibling set is large and the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adds significant behavioral context: it states that CPFs are masked due to LGPD compliance and that the cache duration is 15 minutes. It also mentions that the response includes embedded sub-resources. These details go beyond the schema and help the agent understand what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with only three brief sentences. The first sentence states the core purpose, the second adds key behavioral traits, and the third gives a cache detail. Every sentence is essential and none are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one required parameter, full schema coverage, and an output schema, the description is sufficiently complete. It covers purpose, data privacy implications, performance characteristics, and parameter source. The only minor gap is that it does not explicitly describe the return type, but the presence of an output schema mitigates this need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds value by clarifying that the ID is internal to Comprasnet and may differ from the ID in Dados Abertos, and explicitly states where to get it. This prevents common errors and adds meaningful context beyond the schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it consults the full detail of a contract in Comprasnet via a specific API endpoint. It explicitly distinguishes the parameter source by mentioning that the ID comes from a specific sibling tool, which differentiates it from other contract query tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by noting the ID must be obtained from 'compras_contrato_comprasnet_por_uasg', giving clear context for when to use this tool. It does not explicitly state when not to use it or list alternatives, but the sibling context and parameter description provide reasonable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: it discloses the upstream API behavior (no pagination, large payload), the client-side slicing strategy, and caching details (15 min cache, cheap per-call slicing). This goes far beyond a simple 'list contracts' and provides critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but structured with a clear summary line, followed by important behavioral notes. The bold attention marker is effective for front-loading critical info. Slightly verbose with the Portuguese attention note, but overall efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is an output schema, the description does not need to detail return values. It covers purpose, data source, pagination behavior, caching, and performance implications. For a tool with multiple complex aspects (upstream limitation, client-side slicing, caching), this is exceptionally complete and leaves no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description itself does not add parameter-level details beyond what the schema already provides; all parameters are well-documented in the schema. The description mentions 'pagina + tamanho_pagina' in passing but only in context of the slicing strategy, not adding new semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Lista' (lists) and resource 'contratos de uma UASG no Comprasnet', distinguishing it from siblings like compras_contratos_listar which likely lists contracts from a different system or without UASG filtering. The attention note about pagination further clarifies its exact behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool: when needing contracts by UASG from Comprasnet. It explains the upstream API's lack of pagination and how this tool handles it. However, it doesn't explicitly mention when not to use it or name alternatives among the many sibling tools related to contracts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the 15-minute cache behavior and the dependency on two parameters even though 'codigo' is the only required one. It does not mention error behavior or rate limiting, but the cache note is valuable for expectation management.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three short lines covering purpose, upstream constraint, and caching. Every sentence adds unique value. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 parameters, an output schema exists), the description is mostly complete for a simple contract lookup tool. It covers the key behavioral nuance (cache and parameter requirement) but could mention that the output schema documents the response structure, which is already covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the upstream requirement for both parameters and giving context about accepted types, which goes beyond what the schema provides. It reinforces the relationship between codigo and tipo.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Consulta um contrato no Dados Abertos (endpoint 1.1)', specifying the verb (consulta), resource (contrato), and source system (Dados Abertos). It distinguishes from siblings like 'compras_contratos_listar' by indicating it queries a single contract via upstream endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that upstream requires 'codigo + tipo' and lists the accepted types, giving clear input guidance. However, it lacks explicit statements on when to use this tool versus siblings (e.g., when to use listar vs consultar) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the critical limitation that the tool does not return any price field, lists the exact DTO fields, mentions the endpoint, and states a 10-minute cache. It does not cover error handling or authentication requirements, but for a read-only list tool, the transparency is high and adds significant value beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the core purpose and key limitation. It then provides the endpoint, a warning, field list, alternative tool, and cache duration in a few sentences with no redundant or irrelevant content. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (1 required) and an output schema, the description covers the main behavioral aspects: what it returns, what it does not return, how to get price data, and cache behavior. It mentions the endpoint and DTO fields. The output schema exists, so return description is not needed. Minor omissions like pagination behavior are already covered by parameter descriptions. The description is sufficiently complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description repeats the schema's detail for the required parameter (e.g., 'Código CATSER do serviço. Inteiro 4-6 dígitos. Ex.: 27332') and adds context by linking the parameter to the tool's purpose, but does not introduce new semantic information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists individual purchases of a CATSER service without price. It uses a specific verb ('lista') and resource ('compras individuais de um serviço CATSER') and distinguishes from the sibling tool 'compras_pesquisar_preco_servico' by explicitly noting it does not return price, while the sibling does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to use this tool versus the alternative: 'Para preço unitário de serviço use compras_pesquisar_preco_servico'. It also clarifies the tool's scope (only returns data without price) and provides cache duration, giving clear context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool performs a read operation ('Lista'), specifies the HTTP POST endpoint, and mentions a 1-hour cache. This gives essential behavioral insight. However, it does not address pagination, result limits, or whether any side effects occur (though unlikely).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three, concise sentences. It front-loads the core action, provides the endpoint for reference, explains the use case, and ends with caching info. Every sentence is meaningful with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional params, output schema present), the description covers purpose, usage, and caching. It doesn't mention pagination or maximum number of codes, but the output schema fills the response structure gap. Slightly incomplete for edge cases, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with basic descriptions. The description adds purpose: the parameters are item codes (CATMAT/CATSER) used to find suppliers. This gives semantic meaning beyond the schema's minimal 'a buscar' phrase. It does not detail parameter formats or constraints, but the added context elevates it a point above baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Lista' (lists), the resource 'contratos e empenhos', and the scope 'por itens (CATMAT/CATSER)'. It distinguishes this tool from siblings that list contracts by other criteria or focus on suppliers or items separately. The endpoint and purpose also reinforce specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case: discover who currently supplies given items (by CATMAT/CATSER codes) to identify potential participants in new biddings. This gives clear when-to-use context. However, it does not explicitly state when NOT to use it or name alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value beyond the schema by revealing that the esfera filter is applied client-side, that the total_registros reflects unfiltered counts, the maximum time window, and cache duration. It does not mention authentication, rate limits, or pagination behavior, but these are partially covered by the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, each adding unique value: listing action, endpoint and scope, modality codes, and important behavioral notes (client-side filter, window, cache). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 9 parameters, 3 required, and many siblings, the description covers the core functionality and key caveats. It does not explicitly differentiate from similar listing tools like 'compras_contratacoes_14133_listar', but the scope and modality focus are implied. The presence of an output schema reduces the need to explain return values, making the description adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description adds significant meaning by explaining common modality codes (e.g., 6=Pregão Eletrônico) and clarifying that the esfera filter is client-side with implications on total_registros. It also mentions the 30-day window and cache, which are not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists published contracts in PNCP for a period, with a specific verb ('Lista') and resource ('contratações publicadas'). It mentions the endpoint, scope (all federation entities), and common modality codes, which helps distinguish it from sibling tools like 'compras_pncp_contratacao_por_orgao' that focus on specific orgs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (date range and modality filtering) and includes important caveats like the client-side esfera filter, 30-day maximum window, and 15-minute cache. However, it does not explicitly name alternative tools or state when not to use this tool, leaving room for improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It discloses 'Cache 1h' (1-hour cache), which is a behavioral trait. It also mentions the endpoint URL. While it doesn't cover every detail (e.g., auth requirements, error states), the caching info adds important transparency beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, usage context with alternative, and cache duration. Front-loaded and tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not needed in description), 4 parameters, and enough context from schema, the description covers purpose, usage guidance, and caching. It could mention pagination behavior or error cases, but the schema already covers pagination limits. One minor gap: it doesn't clarify what happens if the user ID is invalid, but that's acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 tool description does not add additional meaning beyond what the schema already provides for each parameter. The description of id_usuario's rarity is in the schema, not the tool description. No extra value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Lista PCAs') and the resource ('vinculados a um usuário/sistema integrador específico'). It distinguishes itself from the sibling tool 'compras_pncp_pca_listar' by specifying the filtering criterion (user vs. CNPJ of órgão).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use this tool: 'Uso menos comum — geralmente o analista prefere compras_pncp_pca_listar com cnpj_orgao.' This gives clear guidance on preference and an alternative, which is excellent for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It explains the search strategy (active first, then inactive), the 'ativa: false' output for extinct UASGs, the 24-hour cache, and a historical bug fix date, providing rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is multi-sentence but each sentence adds value: purpose, return data, use case, behavioral detail, cache. The historical bug note is slightly extraneous but relevant for context. It is well-structured and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, output schema present, and low complexity, the description is exceptionally complete: it covers return fields, search logic, caching, a bug reference, and a use case. The sibling link aids contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'codigo_uasg' is described in the schema as 'Código numérico da UASG.' The description adds 'consulta pelo código' and its utility for resolution, but does not provide additional semantics such as range, examples, or format beyond the schema. With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('consulta') and resource ('uma UASG específica pelo código'), lists the returned fields (nome, sigla, CNPJ, etc.), and distinguishes itself from siblings like compras_uasg_listar by specifying that it is a single-UASG lookup by code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says it is useful for resolving 'codigo_uasg' before filtered queries, and directs to compras_uasg_listar for diagnosing a past 404 issue. It does not explicitly list when not to use, but the context implies alternative tools for listing or searching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses important behaviors: it returns the header of the ata, handles edge cases (wrong input format returns diagnostic instead of silent failure), and mentions a 15-minute cache. It does not address authentication or side effects, but as a read operation on an open data endpoint, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (4 sentences plus a line for endpoint and cache) and front-loaded with the main purpose. Every sentence adds essential information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description need not detail return values. It covers the tool's purpose, parameter semantics, edge-case behavior, and cache policy. It is sufficient for an agent to decide when and how to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter. The description adds significant value by explaining the format with an example, warning against confusion with compra IDs, and detailing the behavior when the format is wrong. This goes beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Consulta uma ARP específica pelo identificador PNCP.' It specifies the verb (consultar), resource (ARP), and identifier type. This distinguishes it from sibling tools that list, search, or retrieve items of ARPs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use the tool (consulting a specific ARP by PNCP identifier) and includes a specific guide on handling the input format (compra vs. ata format). However, it does not explicitly state when not to use this tool or mention alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that it returns 'detalhes completos' listing several fields (objeto, valor estimado, modalidade, instrumento convocatório, status no PNCP) and mentions the cache duration of 15 minutes. No annotations are provided, so this description carries the full behavioral transparency burden – and it does so well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, focused sentences. The first states the core purpose, the second provides the endpoint for reference, and the third lists the return contents and cache behavior. No fluff, all essential information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has only one parameter (fully described), an output schema exists, and the description covers purpose, parameter semantics, detailed return fields, and caching policy, the description is complete enough to enable correct use without requiring additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100% and the description adds context by mentioning that id_contratacao is the internal id returned by listar_contratacoes_14133, which links the parameter to a sibling tool's output. This goes beyond the raw schema definition, providing operational semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (consultar uma contratação 14.133), the resource (pelo id interno), and lists the details returned (objeto, valor, modalidade, etc.). It distinguishes the tool from siblings like compras_contratacoes_14133_listar (which lists, not queries by id) by mentioning that it uses the internal id returned by the list endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an internal id from listar_contratacoes_14133, and the schema reinforces that id_contratacao is required. However, it does not explicitly exclude alternative tools (e.g., when you might use other consult tools) or provide negative examples, but the context is clear enough for the target use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains that this is a discovery tool listing static reference data (domain tables, glossary, metadata). It describes the return structure and notes compatibility with different client types. For a read-only list tool, this provides sufficient behavioral context without needing to mention side effects or auth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet informative. Each sentence serves a purpose: stating the action, providing usage context, explaining resource nature, pointing to related tool, and specifying the return format. It is well-structured with front-loaded purpose and logical flow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are no parameters, no annotations, and an output schema is fully described inline, the description covers all necessary aspects: purpose, when to use, what resources are, how to read content, and output structure. It is complete for a simple list tool without missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema coverage is trivially 100%. The description adds value by explaining the output fields (URI, nome, mime-type, descricao, tags) beyond what the schema conveys. For a parameterless tool, a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists MCP resources with URI, name, and mime-type. It distinguishes from the sibling tool 'compras_obter_resource' by directing to that for reading content, and explains the use case (clients without UI for attachment). The verb 'listar' and resource 'resources' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: for clients like Claude.ai web that don't expose a UI for attaching resources. It contrasts with clients like Claude Desktop where resources appear in a dedicated picker. It also recommends using 'compras_obter_resource' for reading content. While it doesn't list all alternative tools, the guidance is clear and practical for the intended use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is exceptionally transparent: it documents a past upstream breaking change, explaining the root cause (API signature change without versioning), the misleading HTTP 404 behavior, and the resolution date. It also clarifies that upon new 404 errors, the tool returns an error diagnostic rather than raising an exception. With no annotations provided, this description carries the full burden and does so admirably, though it loses one point for not explicitly stating the read-only nature or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: the first paragraph states the core purpose and endpoint; the second clarifies sibling differentiation; the third and fourth provide a critical behavioral note with historical context. Every sentence adds value, and the total length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 8 parameters, no annotations, but a complete output schema. The description compensates fully for the missing annotations: it covers behavioral traits (upstream break, error handling), usage context, and sibling differentiation. There is no significant gap given the tool's complexity and available structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters clearly (e.g., codigo_item_catalogo as CATMAT code, uf as state acronym). The description restates that each response includes fields like precoUnitario and fornecedor info, but adds no new semantic detail beyond the schema's exhaustive descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool queries prices paid by the government for material purchases (CATMAT), using a specific open data endpoint. It explicitly distinguishes itself from sibling tools like `compras_pesquisar_precos_para_etp` (statistical view) and `compras_detalhar_preco_material` (doesn't return unit price), making its unique purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use this tool for per-material unit prices, and directs users to `compras_pesquisar_precos_para_etp` for statistical aggregates per IN 65/2021. It also warns that `compras_detalhar_preco_material` does not return prices, preventing misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses multiple behavioral traits: cache of 24 hours and specific 404 error handling that returns a structured error object instead of throwing an exception, including a reference to consistent patterns in sibling tools. No annotations exist, so the description carries full burden and does so thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but packed with essential information: what it does, the endpoint, when to use it, caching policy, and special behavior. Every sentence is valuable and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single required parameter, no annotations, and an output schema (so return format is covered), the description fully covers the tool's purpose, usage context, caching behavior, and error handling. There is no missing information relevant to an agent deciding to call this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter (cnpj), and the description adds meaning beyond the schema by stating it is a 14-digit CNPJ (with or without punctuation) and provides an example. However, since schema coverage is already 100% and the parameter is simple, the description does not add substantial extra nuance beyond the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists administrative units of a government agency (órgão) in the PNCP system. It specifies the endpoint, identifies its purpose (discovering unit codes before filtering contracts), and distinguishes it from the many sibling tools by mentioning the specific context of PNCP agencies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool is useful before filtering contracts by unit, and covers states and municipalities (not just federal), giving context on when to use it. It does not explicitly exclude other scenarios or provide at-length when-not-to-use guidance, but the use case is clear enough without needing to list all alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses internal behavior: client-side filtering, pagination up to 'max_paginas_varridas', curto-circuit on 'max_resultados', case-insensitive matching with accent normalization, and a known limitation about missing UF field. With no annotations provided, the description carries the full burden and does an excellent job. It loses one point only because it doesn't document whether the operation has any side effects (though likely read-only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, technical context, limitation, output format. It uses Portuguese throughout and is efficient, but could drop the internal note about 'Achado da bateria A v0.3.5' which is meta-information not useful for an agent. Each section earns its place; the text is front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, 100% schema coverage, and an output schema, the description is remarkably complete. It explains the problem it solves, limits, downstream implications, and even provides an alternative tool chain for UF filtering. The caching policy and return structure are documented. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. However, the description adds significant value beyond the schema: it explains the relationship between parameters ('max_resultados' and 'max_paginas_varridas' act as limits), the rationale for defaults (5000 ARPs examined with default pagination), and the caching key ('palavra_chave + janela + caps'). The description also provides examples for 'palavra_chave' and context for 'data_vigencia_final_min' (typically today for vigentes). This is above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for active ARPs (Atas de Registro de Preços) whose 'objeto' contains a keyword. It names a specific verb 'Busca' and resource 'ARPs vigentes', and distinguishes itself from the sibling 'compras_arp_por_fim_vigencia' by explaining this tool solves the limitation of that endpoint not accepting text filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context on when to use this tool versus alternatives. It identifies the upstream limitation of '/modulo-arp/1.2_consultarARP_FimVigencia', documents internal pagination behavior, and includes a specific limitation about UF not being in the upstream schema, offering an alternative workflow with 'compras_uasg_consultar'. It also mentions caching policy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses a 10-minute cache, parallel execution of sub-endpoints, composite-key requirements, and a specific diagnostic handling when the input ID is a compra (without suffix) instead of an ata. This is strong behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense, using a structured list-like format to enumerate the dossier composition. Every sentence provides relevant technical context, including cache and error behavior, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an aggregator tool with an output schema, the description covers composition, optionality, input sourcing, cache, and error handling. It lacks explicit comparison to individual sibling endpoints but otherwise gives enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the origin of the three IDs (from other ARP tools) and the composite key used by the sub-endpoints, going beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Dossiê completo de uma ARP em uma chamada' and enumerates the composition: header plus optional saldo, adesões, and unidades participantes. This specific verb+resource+scope distinguishes it from sibling tools that handle individual components.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool composes multiple endpoints in parallel and that the IDs come from compras_arp_listar or compras_arp_itens_listar. It also notes that omitting numero_item restricts the call to the header, providing clear usage context. However, it does not explicitly state when to prefer this over individual item tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavior: it returns raw content and metadata, describes the return format with a JSON example, and explicitly states that if the URI does not exist it returns `_erro` instead of propagating an exception. This covers all key behavioral traits beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then provides additional detail on return format and error behavior. Every sentence adds value. A small improvement could be removing the blank line at the start.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and includes an output schema in its description, the description is complete. It covers what the tool does, how to use it, what it returns, and error handling. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds significant value by including a JSON example of the return value and explaining error handling. The parameter `uri` has a detailed description with examples of valid URIs, making it easy to use. The description of the output complements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Lê' (reads) and the resource type 'MCP Resource pela URI'. It distinguishes itself from 'compras_listar_resources' by referencing it in the parameter description as the way to discover URIs. The description also explains the error handling behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use 'compras_listar_resources' to discover available URIs, providing clear guidance on how to prepare for this tool. It does not explicitly state when not to use it, but the purpose is narrow enough that misuse is unlikely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It thoroughly describes the tool's behavior: parallel composition from four sources, each with details about what data they return (e.g., razão social, CNAE, QSA, etc.). It explicitly states what is excluded (contracts) and why, discloses dependencies (API key, potential WAF blocks), and mentions a 10-minute cache. This is comprehensive behavioral transparency for a complex data integration tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and bullet points. Each sentence adds value: the main purpose, component breakdown, exclusion rationale, dependency notes, and cache. It is front-loaded with the core purpose. However, the explanation about contract exclusion is somewhat lengthy (three sentences) and could be slightly condensed without losing clarity. Overall, it is efficient but not perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (four parallel data sources, dependencies, and an output schema), the description is complete. It covers what it does, what it includes/excludes, how each source works, dependencies, and caching. Since an output schema exists, it need not describe return values. The description also references a sibling tool for an alternative use case. There are no gaps in context for an agent to correctly invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'cnpj' has schema coverage of 100%, with a description in the schema. The tool description adds context by reaffirming the format '14 dígitos, com ou sem pontuação' and explaining how the CNPJ is used to consolidate data from multiple sources. This adds meaning beyond the schema, showing the parameter's role in the broader tool purpose. However, the schema already provides format details, so the added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Perfil consolidado do fornecedor' and lists four specific data sources (cadastro, receita_federal, sanções, impedimentos). It distinguishes itself from sibling tools by explaining what is NOT included ('Não inclui lista de contratos') and why, referencing specific endpoints and alternative tools. The verb-phrase 'compras_perfil_fornecedor_completo' is clearly described as a consolidated profile, and the inclusion of exclusions differentiates it from contract-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when not to use it (if contracts are needed, use 'compras_contratos_listar' with specific parameters). It also mentions dependencies like 'TRANSPARENCIA_API_KEY' and potential blocking by WAF. However, it does not explicitly compare to sibling tools that provide only partial profiles (e.g., compras_fornecedor_consultar, compras_fornecedor_cnpj_receita), leaving some ambiguity about when to choose this over simpler alternatives. A clearer statement of 'use this when you need the full profile; use the simpler tools for just basic data' would improve it, but the existing guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly discloses that CPFs are masked per LGPD (showing example format) and that results are cached for 1 hour. With no annotations provided, these behavioral details are essential and fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with only three short bullets (title, endpoint/usage, behavior notes). Every sentence adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and schema coverage is full, the description covers key behaviors (masking, caching). It could mention the maximum number of results per page or that pagination is available, but it's functionally complete for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well-documented. The description adds no new info about parameters but reinforces the overall context. A slight deduction for not explaining pagination purpose or limit, but the schema covers it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for querying the CEAF database of federal employees expelled from public service. It specifies the endpoint and notes the useful scenario of investigating a suspect representative. This distinguishes it from sibling tools dealing with other sanction registries (e.g., CEIS, CNEP, CEPIM).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is useful when identifying a suspect responsible party. It does not explicitly state when not to use it or name alternatives, but the context of sibling tools (like compras_sancao_ceis and compras_sancao_cnep) suggests other sanction databases exist. The guidance is clear enough for a focused tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is exceptionally transparent about historical bugs (404 vs 400, missing parameter diagnosis), logical defaults (ativo defaults to True), pagination quirks (upstream ignores tamanho_pagina, fixed 500-record pages), and caching (24h). No annotations were provided, so the description carries full burden and exceeds expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed and well-structured, front-loading the core purpose. It includes essential behavioral notes and historical context without excessive fluff. Slightly longer than necessary due to the historical bug narrative, but each section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (pagination oddities, default behavior, historical bug) and presence of output schema (context signal), the description covers all necessary aspects: what the tool does, how defaults work, pagination behavior, relevant history, and cache policy. It leaves no obvious gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already has 100% coverage with descriptions for all 4 parameters. The description adds value by explaining the link between 'ativo' and the underlying API parameter 'statusUasg' (not exposed directly), and the behavior of 'tamanho_pagina' being effectively ignored. Notably, it does not describe 'codigo_orgao' in the description, but the schema covers it well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists UASGs (Unidades Administrativas de Serviços Gerais) from the government, specifying verb 'listar' and resource 'UASGs'. It distinguishes from siblings like 'compras_uasg_consultar' and 'compras_uasg_buscar' by focusing on listing/filtering rather than individual lookup or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool, including the dominant use case ('ativo' defaults to True for active UASGs) and pagination behavior. However, it lacks explicit guidance on when not to use it or alternatives among siblings (e.g., when to use consultar vs listar).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses caching (24h), error behavior (404/upstream errors return encontrado=false with _erro), and data source (BrasilAPI/MinhaReceita). It implicitly indicates read-only via 'consulta'. However, it does not explicitly state that the tool is read-only or has no side effects, which would be a minor improvement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: first line states purpose, then lists return fields, followed by usage guidance, note about sanctions, and caching/error behavior. Each sentence is necessary and contributes to understanding. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, clear output (output schema exists), and many sibling tools, the description covers all key aspects: what it returns, when to use it, how it differs from other tools, data source, caching, and error handling. The agent has enough information to decide when and how to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage with a description for the cnpj parameter. The description adds value by specifying the exact format (14 digits, with or without punctuation) and mentioning the provider switching via environment variable. This goes beyond the schema, but the schema already handles the basics, so the additional info is welcome but not critical.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns public CNPJ data from Receita Federal, lists specific return fields, and explicitly distinguishes from sibling tools like compras_perfil_fornecedor_completo and sanction tools. The verb 'consulta' and resource 'Dados públicos do CNPJ' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Quando usar' section that tells when to use this tool (due diligence complement of compras_perfil_fornecedor_completo) and explicitly says not to use it for sanctions, directing to sanction tools. It also mentions cache duration and error handling behavior, providing clear when-to and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly indicates this is a read-only discovery tool (listing prompts) and describes the return structure. However, it could benefit from explicitly stating that it has no side effects and requires no special permissions or parameters, though this is implied by the 'discovery' context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: first stating the primary purpose, then providing usage context (when to use vs. native UI), followed by a usage workflow hint, and finally a clear return format. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an explicit output schema, the description is complete. It explains why this tool exists (for clients without prompt UI), how to chain it with another tool, and exactly what the response structure looks like. There are no gaps in understanding for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description's role is to explain what is listed. The description does this well by detailing the return format including fields like 'nome', 'descricao', 'tags', and 'argumentos' with subfields. Since schema coverage is 100% (no parameters), a baseline of 4 is appropriate — the description adds clear semantic meaning about what to expect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists MCP Prompts with name, description, and arguments. It explicitly distinguishes this from other tools in the sibling list, especially the companion tool 'compras_obter_prompt' for rendering a specific prompt.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: for clients that don't expose a UI for prompts (like Claude.ai web) and are not substitutes for dedicated UIs in Claude Desktop/Cursor/MCP Inspector. It also tells the user to follow up with 'compras_obter_prompt' to render a specific prompt, providing clear workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It clearly states this is a read-only diagnostic tool that returns version, upstream sources, and configuration status without exposing sensitive values. It also mentions the specific dependency on the Transparency key for sanctions tools. A slight deduction is warranted because it doesn't explicitly state the tool has no side effects or guarantee zero cost.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, each earning its place. The first sentence defines core output; the second sentence clarifies practical utility and a prerequisite. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no inputs, no annotations, and an output schema exists (so return format is handled), this description is complete. It covers purpose, output content, usage context, and a dependency. There is no missing information that would hinder correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% (no parameters to describe). The description adds value by explaining what the response contains, which is more meaningful than the empty schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this tool is a 'Healthcheck/diagnóstico do MCP' and specifies what it returns: version, upstream sources, and configuration status of sensitive settings. This distinguishes it from all sibling tools, which are focused on procurement, contracts, sanctions, or other specific data queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description is explicit about when to use this tool: 'confirmar que o servidor está respondendo, qual a versão instalada, quais APIs estão acessíveis e se a chave da Transparência foi configurada.' It also names a prerequisite ('necessária para tools de sanções'), which helps the agent decide whether this is a needed preliminary step. No alternative tool is listed among siblings, so the description effectively stands alone as the diagnostic entry point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It fully discloses that this tool does NOT return price, documents the exact fields in the upstream DTO, confirms the absence of price field via two verification methods, and specifies a 10-minute cache. This is exemplary transparency beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a bold warning, clear sections for endpoint, data fields, verification, and usage guidance. It is slightly lengthy due to detailed audit documentation but every sentence adds value. The critical information is front-loaded with the 'no price' warning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, 100% schema coverage, existing output schema), the description is exceptionally complete. It explains the tool's purpose, limitations, data fields, verification methodology, cache behavior, and correct alternative for price queries. No gaps remain for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameter descriptions provided, so baseline is 3. The description adds value by explaining the scope (lists purchases for a CATMAT item), the endpoint path, and the data_fim/data_inicio default behaviors. However, it doesn't explicitly describe the pagination or codigo_item_catalogo parameters beyond the schema. The price disclosure context does not enhance parameter understanding further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists individual purchases of a CATMAT item without price data. It specifies the exact DTO fields returned and differentiates from the sibling tool 'compras_pesquisar_preco_material' for price queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (detailed item description, purchase object, idCompra tracking) and when not to (for unit price), directing the agent to the correct alternative 'compras_pesquisar_preco_material'. It also explains the data source limitation with audit evidence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It fully discloses the critical upstream bug (textual filter ignored, returning entire universe), confirms the behavior via probe, specifies that the `termo` parameter is still sent for compatibility but ineffective, mentions the emission of `_aviso_filtro` when the universe is returned, and notes 24-hour caching. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose. It then uses a clear warning header, a bulleted workflow, and a concise note about behavior and caching. Every sentence is informative and necessary. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, 1 required, output schema exists, 100% schema coverage), the description covers everything an agent needs: purpose, when to use, broken behavior, recommended approach, and caching policy. It is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the upstream bug and recommending structural filters strongly. It also clarifies that `termo` is still sent but not effective. These context-rich hints go beyond the schema's parameter descriptions, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with "Busca itens CATMAT." providing a clear verb+resource purpose. It also outlines a recommended workflow involving sibling tools (listar_grupos, listar_classes) to compensate for the broken textual filter, effectively distinguishing this search tool from listing and consultation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using structural filters (codigo_grupo, codigo_classe) instead of relying on the textual filter due to the upstream bug. It provides a step-by-step workflow using sibling tools to first obtain group and class codes, then use this tool with those filters. This is clear guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It excels by explaining in detail: the parallel probe with short timeout, retry logic for slow routes ('Rota que estoura o relógio é reexecutada em série antes de virar `fora`'), the `pronto_para_uso` summary field, and each possible status (`ok`, `degradado`, `fora`, `pulado`) with precise meaning. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear opening summary, a motivating backstory (why it exists), explicit Args section, and a detailed explanation of statuses and retry logic. Every sentence adds unique value, and the information is front-loaded. It is appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, full schema coverage, and an output schema, the description is complete. It explains the purpose, behavior, parameters, statuses, and edge-case handling (retries, silent failures). The output schema documentation is not needed here because the description sufficiently describes the return values and fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters well. The description adds significant value by providing context on the `rotas` mode behavior and the list of possible `modulo` values, and by explaining the trade-off between speed (`basico`) and depth (`rotas`). However, the core parameter definitions are already in the schema, so a slight deduction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it checks what is currently running on the server ('o que está de pé neste servidor agora') and extends `compras_versao` by adding a parallel probe against upstream routes. It also distinctly differentiates itself from the many sibling tools by emphasizing its health-check/monitoring role, unlike any other tool listed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('Antes de uma demonstração ou de instruir processo, rode isto') and gives a concrete real-world example of a situation it prevents. It also clearly explains the two modes (`basico` vs `rotas`) and the optional `modulo` filter, ensuring the agent knows exactly how to run it in different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: it discloses that textual filters are non-functional (ignored by upstream), specifies the total count of active agencies (~11.8k), mentions 24-hour caching, and notes the tool was restored after a param issue. This is far beyond basic annotation-level info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: description of the tool, endpoint, restoration note, critical filter warning with alternative, and cache policy. Front-loaded with the core purpose, then immediately addresses important caveats. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with an output schema, the description is remarkably complete: it explains the data scope (SISG), fields returned, non-functional parameters, alternative tool for specific queries, restoration history, and caching. The existence of an output schema reduces the need to explain return values, but the description still adds essential behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explicitly stating that nome, esfera, and poder filters are non-functional, which contradicts what the schema descriptions imply (they are listed as functional filters). This warning is critical for proper agent usage, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists cadastrated government agencies (orgãos) from Compras.gov.br, providing the specific data source endpoint and listing the fields returned. This distinguishes it well from siblings like compras_orgao_consultar, which is for querying a specific agency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when NOT to use textual filters (they are ignored) and directs the agent to use compras_orgao_consultar with codigo_orgao for finding a specific agency. It also warns about a param issue that was fixed, giving clear alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavioral traits beyond annotations (none provided). It details caching (24h), upstream limitations (no textual filter, requires statusUasg), the local filtering approach, pagination logic (fetches pages until matching or truncation), and explicit response markers to indicate truncation. This is exemplary transparency for a tool that works around upstream constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed and well-structured, with a clear title line followed by a changelog/context section. The bullet for the 'nome' parameter issue is helpful but slightly verbose. Every sentence adds value, but the changelog-style update note could be slightly more concise. Overall, it's well-organized and front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description doesn't need to explain return values. The tool is moderately complex (3 parameters, local search workaround with caching and pagination), and the description covers its behavior comprehensively: when the upstream returns 404, why the nome parameter was problematic, how local search works, caching TTL, and response markers. This leaves an agent fully equipped to use the tool correctly without surprises.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% description coverage (all three parameters have descriptions). The tool description adds minimal extra info beyond the schema (e.g., the update note about caching and upstream issues), but the schema descriptions are themselves comprehensive: termo explains match type, character limits, and gives examples; pagina explains 1-based indexing; tamanho_pagina explains default and max. The description and schema together provide full parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Busca UASGs por trecho do nome' (search UASGs by name fragment), specifying it uses partial match, ignores accents and case. This uniquely distinguishes it from siblings like 'compras_uasg_listar' (lists) and 'compras_uasg_consultar' (detailed query). The description explicitly notes the match is literal and mentions example terms, leaving no ambiguity about the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when and how to use this tool: it performs local search because the upstream API has no textual filter. It warns that sending a nome parameter to the upstream would return the entire universe (22k UASGs) as false matches. It clarifies the polling behavior (500 records per page, ~8s full scan, 24h cache), so users know only the first daily query pays the cost. It also tells that the response contains _busca_local, _paginas_varridas, and _universo_varrido markers. No sibling is a direct alternative for name-based search, so the tool's distinct use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![MCP_Compras MCP server](https://glama.ai/mcp/servers/opedrosoares/MCP_Compras/badges/card.svg)](https://glama.ai/mcp/servers/opedrosoares/MCP_Compras)

Score Badge

Copy to your README.md:

[![MCP_Compras MCP server](https://glama.ai/mcp/servers/opedrosoares/MCP_Compras/badges/score.svg)](https://glama.ai/mcp/servers/opedrosoares/MCP_Compras)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/opedrosoares/MCP_Compras'

If you have feedback or need assistance with the MCP directory API, please join our Discord server