Olist MCP

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation3/5
Most tools target distinct resource-action pairs (e.g., contato vs produto vs pedido), but there are overlapping invoice operations (nota_fiscal_incluir, nota_fiscal_consumidor_incluir, incluir_nota_xml, pdv_incluir_nota_xml) and inconsistent search variants (expedicao_pesquisa vs expedicao_pesquisar_agrupamentos) that could mislead an agent. The 92-tool scale also makes it hard to select the right tool without deep inspection.
Naming Consistency2/5
The 'olist_' prefix is consistent, but the pattern mixes noun forms (pesquisa, lista, excecoes, info) with infinitive verbs (pesquisar, incluir, obter, alterar) and sometimes places verbs before the object (incluir_nota_xml vs nota_fiscal_incluir). Some tools are pure nouns (pdv_pedidos, pdv_produtos), and 'pesquisar' appears only once while all other searches use 'pesquisa'.
Tool Count1/5
92 tools is far beyond the practical range for a coherent MCP server, making discovery and selection extremely difficult. Even for a broad ERP API, the tool set should be consolidated (e.g., grouping operations by resource or using parameters) to remain navigable.
Completeness2/5
The server covers many domains (contracts, products, CRM, orders, invoices, expedition), but lifecycle coverage is inconsistent: many resources have create/get/update/search but no delete (products, contacts, orders, invoices), while others (vendedores, formas_recebimento) are read-only. This leaves dead ends and prevents full workflows without external workarounds.
Average 3/5 across 92 of 92 tools scored. Lowest: 1.7/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 status not available
This repository is licensed under MIT License.
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

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavior. It fails to mention any behavioral aspects such as pagination, response format, required permissions, or side effects. The user is left with no information beyond 'search expeditions'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (three fragments), but the endpoint line ('expedicao.pesquisa') is redundant with the tool name and the initial phrase. It lacks structured presentation, such as a clear summary or usage hints, but it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is critically incomplete for a search tool with no output schema. It does not state what the response contains, how pagination works, or any exclusions (e.g., the required formaEnvio parameter). Even the documentation link is an external reference rather than inline 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?
The input schema provides descriptions for all 6 parameters (100% coverage), which is the baseline for a high-coverage schema. The description itself adds no parameter-level meaning, but the schema already handles this adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Pesquisar expedições' is essentially a tautology of the tool name (olist_expedicao_pesquisa). It mentions 'API 2.0' and the endpoint, but these do not clarify the scope or differentiate it from sibling tools like olist_expedicao_pesquisar_agrupamentos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/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. There is no context about required parameters (e.g., formaEnvio), filtering by date, or distinguishing from the agrupamentos search. The description is purely a statement of existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior, but it only states it is an API 2.0 endpoint. It does not indicate whether this is a read-only operation, how pagination works, or what data is returned. No behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but under-specified. It contains a title-like phrase, an endpoint identifier, and a docs URL, but omits the core action and semantics. This is under-specification rather than true conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema and no annotations, the description is far from complete. It fails to state purpose, usage, or expected results, leaving the agent without enough context to invoke it 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?
The input schema already has 100% parameter descriptions, so the baseline is 3. The description adds no additional meaning about how parameters interact or what an 'exception' entails.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description only restates the resource name ('Exceções das Listas de Preços') and provides an endpoint/docs link, without any verb indicating the action (e.g., list, get, create). It does not differentiate from sibling tools like `olist_listas_precos_pesquisa`.
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. It does not mention conditions, prerequisites, or exclusions. The only context is an API endpoint and a documentation link.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 disclosure. It only states the endpoint and a documentation link, giving no information about return format, authentication, side effects, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but under-specified, not genuinely concise. It repeats the tool name and provides an API endpoint that adds little value. Every sentence should add information, but here the content is redundant or purely referential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with no output schema, the description is completely inadequate. It does not indicate what data is returned, how to interpret the response, or any contextual usage info, leaving an agent without enough to select or invoke the 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?
The input schema provides 100% coverage for the single 'id' parameter with a clear description ('Número de identificação do pedido na Olist'). The description adds no additional meaning beyond the schema, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Obter Pedido' is essentially a restatement of the tool name (olist_pedido_obter = get order). It does not add any scope or differentiation from sibling tools like olist_pedidos_pesquisa or olist_pedido_alterar, making it a tautology.
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?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, context, or exclusions. The documentation link is not a substitute for usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavioral traits. It fails to mention that this is a read-only retrieval, what data is returned, error behavior, or any side effects. The word 'Obter' implies getting, but the description does not state what the agent should expect regarding the operation'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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded with the endpoint name. However, it is under-specified and does not earn its place by adding meaningful information; it mostly repeats the tool name. The documentation link is valuable but the core content is tautological.
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?
The tool has no output schema and no annotations, so the description must explain what the tool returns or what the 'obter' operation entails. It fails to describe the return values, field availability based on the optional 'obter_link_boleto' parameter, or any fallback behavior. The documentation link might help, but the description itself is incomplete 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?
Schema description coverage is 100%, so the baseline is 3. The schema already provides meaningful descriptions for both 'id' and 'obter_link_boleto'. The tool description adds no additional parameter semantics beyond what the schema offers, so a baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Obter Conta a Receber API 2.0' essentially restates the tool name without explaining what a 'Conta a Receber' is or what the tool does beyond fetching. It adds an endpoint identifier and documentation link, but these do not clarify the resource or action. It fails to distinguish itself from sibling 'obter' tools.
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?
There is no guidance on when to use this tool versus alternatives like olist_contas_receber_pesquisa or olist_conta_receber_baixar. No context is provided about prerequisites, typical use cases, or exclusions. The description simply names the tool and provides a docs link, leaving the agent without decision-making support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure, but it only repeats the action 'search sellers.' It omits critical behavioral details such as pagination behavior, response format, search semantics, and any prerequisites or side effects, making it entirely uninformative about how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but not well-earned: the first sentence restates the tool name, and the second provides an endpoint identifier and documentation link. It could be improved by adding substantive behavioral or usage information in the same amount of space.
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 simple search tool with no output schema and no annotations, the description should at least mention return values, pagination, or search scope. It provides none of this, instead deferring to an external documentation link, leaving the agent with insufficient context to invoke the tool confidently.
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 already provides descriptions for both parameters (pesquisa and pagina), achieving 100% schema coverage. The description adds no extra parameter meaning beyond pointing to an external documentation URL, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Pesquisar Vendedores' is essentially the same as the tool name (olist_vendedores_pesquisa), restating the resource without adding functional detail. The additional endpoint and documentation link do not clarify the tool's purpose beyond what the name already implies.
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 the numerous sibling search tools (e.g., olist_contatos_pesquisa, olist_produtos_pesquisa). There is no mention of context, exclusions, or alternatives, leaving the agent to guess based solely on the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral-disclosure burden, yet it discloses nothing about pagination, return shape, filter behavior, or response semantics. It only restates the search action and points to an external docs URL; the word 'Pesquisar' implies a read operation but no observable behavior is described.
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 and front-loaded: purpose/version, endpoint, and docs URL are given in three short clauses. Minor redundancy exists ('API 2.0' vs 'API V2', the resource appearing in both the purpose and endpoint), but overall every clause contributes a distinct, useful piece of information.
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 an 8-parameter search tool with no output schema and no annotations, the description is under-specified. It tells the agent what endpoint to call and where to find docs, but not what the response looks like, how pagination works, or what occurs when no filters are supplied—important gaps given all parameters are optional.
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 even without parameter details in the description. The description itself adds no parameter semantics—it mentions only the endpoint and docs—while the schema already documents all 8 parameters, including the dd/mm/yyyy date formats and the 'pagina' page-number field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's core function—'Pesquisar Contas a Pagar' (Search Accounts Payable)—and adds the API V2 endpoint string and a documentation URL. However, the phrase 'Pesquisar Contas a Pagar' is essentially a restatement of the tool name (contas_pagar_pesquisa), and it does not differentiate this search from sibling tools such as olist_contas_receber_pesquisa or clarify what the search returns.
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 when-to-use guidance is provided. The description never mentions when to choose this search over related siblings (e.g., olist_conta_pagar_obter for a specific payable, olist_contas_receber_pesquisa for accounts receivable), and no prerequisites, exclusions, or typical scenarios 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?
With no annotations, the description must disclose behavior, but it only repeats the schema's mutation and confirmation requirement. It does not mention side effects, reversibility, permissions, or what happens if the operation fails. The documentation URL is helpful for further reading but does not add behavioral transparency in the description itself.
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 well-structured, using three short sentences to convey the API version, endpoint, documentation link, and key requirement. It avoids unnecessary fluff, though the brevity comes at the cost of missing explanatory content.
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 one parameter, no output schema, and no annotations, the description fails to provide enough context to understand what 'inscricao' refers to, what data is affected, or what the expected outcome is. The documentation link partially mitigates this, but the description alone is inadequate for proper tool selection and invocation.
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?
All parameters are covered by the schema (100% coverage). The single parameter 'confirmar' is already well-described with a const true constraint. The description's phrase 'exige confirmar=true' adds no additional meaning beyond the schema, 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.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description restates the endpoint name ('inscricao.incluir') and identifies the domain as 'Inscrição API 2.0', but it does not explain what 'inscricao' means or what operation is actually performed. 'Esta operação altera dados' is a generic tautology that adds no specific resource or action, failing to distinguish it from sibling 'incluir' tools.
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?
There is no explicit guidance on when to use this tool versus alternatives. The only usage-related mention is the mandatory confirmar=true flag, which is also present in the schema. No scenarios, exclusions, or comparisons with sibling operations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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, but it only states 'Pesquisar Pedidos' and gives an endpoint. It does not mention that this is a read/search operation, any required authentication, pagination behavior, or what the response contains. This is a severe gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and mostly to the point, but there is redundancy ('API 2.0' vs 'API V2') and it lacks structural elements like sections or usage context. It is not verbose, but it under-specifies, so a middle score is fair.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a search tool with 16 optional parameters, no annotations, and no output schema. The description does not explain the return format, how filters interact, pagination, or any example use cases. This is completely inadequate for the tool's complexity, leaving the agent with only the schema to infer behavior.
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 16 parameters. The tool description adds no parameter information beyond the schema, so the baseline of 3 is appropriate. The schema already explains each field, so no additional value is needed.
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 as 'Pesquisar Pedidos' (Search Orders), which is a specific verb and resource. It also provides the exact endpoint (pedidos.pesquisa), which helps distinguish it from other order-related operations like olist_pedido_obter, though it does not explicitly mention alternatives.
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 such as olist_pedido_obter or other search tools. It only gives a documentation link, which is not embedded guidance, and no exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must disclose behavioral traits. It only provides an endpoint and documentation link, with no information about pagination, return format, filtering semantics, or permissions. This is a significant gap for a search tool with ten optional parameters.
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 one sentence and a documentation link. It front-loads the action, though it includes endpoint and documentation details that may be of limited value to an AI agent. Still, it is efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has ten optional parameters, no output schema, and no annotations. The description offers only the basic action and endpoint, with no explanation of how the search works, pagination, or result structure. It is severely incomplete for an agent to select and invoke the 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?
The input schema has 100% coverage—all ten parameters include descriptions. The description adds no additional meaning beyond the schema, so it earns the baseline score of 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 'Pesquisar Notas de Serviço' (Search Service Notes), identifying the specific action and resource. It provides a clear verb+resource structure, but does not explicitly distinguish from the sibling tool 'olist_nota_servico_consultar', which may also involve searching or consulting notes.
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?
There is no guidance on when to use this tool versus alternatives. The description does not mention preferred use cases, exclusions, or compare with other search tools like 'olist_notas_fiscais_pesquisa' or 'olist_nota_servico_consultar'. Usage is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Sem anotações, a descrição deveria assumir a responsabilidade de transparência, mas não menciona comportamento, paginação, limites, autenticação ou se a operação é somente leitura. Nenhuma característica comportamental é divulgada.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A descrição é extremamente curta, consistindo em um rótulo e um link. É concisa, mas subespecificada; não há elaboração sobre funcionalidade ou uso, tornando a concisão mais uma falta de conteúdo do que uma escolha eficiente de estrutura.
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?
Com apenas um parâmetro e sem schema de saída, a descrição deveria explicar o retorno esperado, comportamento de paginação e relação com ferramentas similares. O link de documentação é útil, mas a descrição em si não fornece contexto suficiente para uso correto.
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?
O schema descreve o único parâmetro 'pagina' com 'Número da página' (cobertura 100%). A descrição da ferramenta não adiciona detalhes adicionais, como valor padrão, intervalo ou comportamento de paginação, mas o schema já cobre a semântica básica.
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 identifica claramente a ação (Pesquisar Pedidos) e o contexto (PDV), e fornece o endpoint da API. No entanto, não diferencia explicitamente de olist_pedidos_pesquisa, embora o prefixo PDV ajude.
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?
Não há orientação sobre quando usar esta ferramenta em vez de outras ferramentas de pesquisa de pedidos, nem condições de uso. Apenas fornece um link de documentação, o que é insuficiente para guiar a seleção entre alternativas.
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?
With no annotations, the description carries the full burden, but it only says 'altera dados' (changes data) and repeats the schema's confirmar=true constraint. It fails to disclose side effects, whether the operation is reversible, prerequisites, or what data is affected.
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 and front-loaded, but the opening phrase duplicates the tool name. It efficiently includes the API endpoint and a documentation link, making it reasonably concise and structured.
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 mutating tool with no annotations and no output schema, the description is too sparse. It does not explain the operation's outcome, when to invoke it, or what the response might be. The documentation URL helps but is not sufficient inline 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?
The schema already fully describes both parameters (id as the order ID, confirmar as a boolean constrained to true). The description adds no additional meaning beyond restating confirmar=true, so it earns the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Lançar Contas do Pedido' and provides the endpoint, but it never explains what 'lançar contas' actually does (e.g., posting financial accounts). It is specific in naming the resource (order accounts) and action, but remains functionally vague without domain knowledge.
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 on when to use this tool versus alternatives is provided. The only extra sentence warns that the operation alters data and requires confirmar=true, which is a constraint but not a usage directive. It does not contrast with related siblings like olist_pedido_estornar_contas or olist_nota_fiscal_lancar_contas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions only the API version and endpoint, with no behavioral transparency. It does not disclose return formats, pagination behavior, required authentication, or side effects. With no annotations, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one line), but the endpoint and version information are redundant with the tool name and provide little value. It is concise but not optimally structured for an agent.
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 search tool with 7 parameters and no output schema or annotations, the description is inadequate. It omits what the search returns, how pagination works, and any constraints on parameter combinations.
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 descriptions cover 100% of parameters, so the baseline is 3. The description adds no additional parameter semantics or interaction details, leaving the schema to carry the full load.
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?
Description clearly states 'Pesquisar Produtos' (Search Products), identifying the tool as a product search operation. It distinguishes from sibling tools like 'olist_produto_obter' (get product) and 'olist_produto_incluir' (include product), though it could elaborate on the scope of search.
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 usage guidance is provided. The description does not specify when to use this tool versus other search tools (e.g., olist_contatos_pesquisa) or how to refine searches. The doc link may contain this but is not accessible to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must itself disclose behavior. It does not mention whether this is a read-only operation, what it returns, pagination details, or any side effects. The description is effectively just a title and reference, offering no 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, which is generally positive, but it is under-specified. It consists of a brief phrase and endpoint reference, with no structured explanation of purpose or usage. It is not as empty as a pure tautology, but it lacks the substance expected of a well-rounded tool description.
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?
With 5 parameters, no annotations, and no output schema, the description is quite incomplete. It does not explain what a successful search returns, how results are structured, or any constraints like date formats (though the schema covers some). The documentation link could help, but the description itself is not self-contained.
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 covers 100% of parameters with descriptions, so the baseline is 3. The description does not add any additional parameter semantics beyond the schema, but it doesn't need to since the schema is thorough.
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 'Pesquisar Separações' (Search Separations), which clearly identifies the verb (search) and resource (separations). It also references the API endpoint, which reinforces the tool's purpose. However, it does not explicitly differentiate from the sibling 'olist_separacao_obter', though the search-versus-get distinction 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 instead of alternatives like olist_separacao_obter or olist_separacao_alterar_situacao. It only gives an endpoint name and a documentation link, which is not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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 only says 'Pesquisar' without stating whether it's read-only, pagination behavior, authentication needs, or what the response contains. This is a significant transparency gap.
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 only two short sentences. The second sentence provides endpoint and documentation link, which is useful but could be trimmed. No unnecessary fluff.
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 being a simple search tool (2 parameters, no output schema), the description fails to explain what the search returns, pagination limits, or any filter behavior. The documentation link is not a substitute for describing expected output and usage 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?
The schema already provides a 100% description coverage for both parameters ('pagina' and 'pesquisa'), so the baseline is 3. The tool description adds no additional meaning or context about the parameters beyond what the schema states.
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 identifies the operation as 'Pesquisar Grupo de Tags' (search tag groups), with a specific verb and resource. It distinguishes from sibling tools like olist_tag_pesquisa by naming the resource as 'Grupo de Tags', though it doesn't explicitly contrast them.
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 such as olist_tag_pesquisa. There is no mention of prerequisites, scenarios, or exclusions, leaving the agent to infer usage only from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It does not disclose any behavioral traits such as authentication needs, pagination behavior, return format, or any side effects. The only extra information is the API version and documentation URL, which do not describe behavior.
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. It front-loads the purpose and then provides a reference to documentation. No redundant or verbose language is present, though the endpoint and URL could be considered somewhat redundant with the tool name.
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 no output schema and simple parameters, the description should explain what the tool returns and how pagination works. It does not. The parameter 'pagina' hints at pagination, but the description does not elaborate, leaving the agent with incomplete 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?
The schema description coverage is 100%, with both parameters ('pagina' and 'pesquisa') documented. The description itself adds no parameter-specific information beyond the schema. Per the rubric, the baseline is 3 when schema coverage is high, and the description does not lower or raise this.
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 'Pesquisar Listas de Preços' (Search Price Lists), which is a clear verb+resource statement. It also specifies the API endpoint, but it does not explicitly differentiate from sibling tools like 'olist_listas_precos_excecoes'. The purpose is clear 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor any exclusions. It only states the endpoint and documentation URL, which does not help the agent decide when to invoke this tool.
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 states the endpoint and provides a documentation link; it does not disclose what the tool returns, whether it can fail, required permissions, or any side effects. The verb 'Obter' implies a read operation, but no further behavioral traits are described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and contains no wasted words, but it is under-specified. It front-loads the tool name and endpoint, yet it does not provide enough useful content to be considered well-structured for an agent.
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?
The tool is simple (one required parameter, no output schema), but with no annotations and no description of return values or error behavior, the description is incomplete. The documentation link is useful but does not substitute for inline guidance about what the tool does or when to use it.
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 describes the single parameter 'id' as 'Número de identificação do contato na Olist' with 100% coverage, so the description does not need to add much. It adds no parameter-level details beyond the schema, but the baseline of 3 is appropriate because the schema already covers the parameter fully.
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 identifies the operation as 'Obter Contato' and specifies the API endpoint 'contato.obter', giving a specific verb and resource. However, it does not explicitly differentiate this from the sibling search tool 'olist_contatos_pesquisa' or mention that it retrieves a single contact by ID.
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?
There is no guidance on when to use this tool versus alternatives. No mention that it should be used when a contact ID is known, or that search should be used to find contacts. The endpoint name implies get-by-ID, but no explicit usage context or exclusions are provided.
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 states 'Esta operação altera dados e exige confirmar=true', but this largely duplicates the schema's confirmar parameter description (which already says 'operação mutável' and const true). No new behavioral traits are added, such as side effects, reversibility, permissions, or what happens to existing data. With no annotations, the description fails to carry the behavioral burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but not optimally structured. It begins with a fragment that restates the tool name, then includes endpoint and documentation URL, and finally a behavioral sentence. The endpoint and URL are somewhat redundant noise for an agent, making it less concise than a clean two-sentence description.
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 lack of output schema and annotations, the description should explain what the operation does, what it returns, and when to use it. It does none of these. It also fails to differentiate from similar tools like olist_pedido_lancar_contas. The provided endpoint and docs link are helpful but not sufficient for an agent to fully understand the operation's effect.
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 id and confirmar having clear descriptions. The tool description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 applies.
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 identifies the tool as 'Lançar Contas da Nota Fiscal' (launch accounts for fiscal note), which is a specific verb+resource. It distinguishes from siblings like olist_nota_fiscal_lancar_estoque by using 'contas' vs 'estoque'. However, it does not fully elaborate what 'lancar contas' entails, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, use cases, or exclusions. The only contextual hint is that it alters data and requires confirmar=true, which is more about behavior than usage selection.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It only implies a read operation via 'Obter' (get). It does not disclose return format, error behavior, authentication needs, or any side effects. This is a minimal disclosure not adding meaningful context beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point but structured as fragments: 'Obter Separação API 2.0. Endpoint API V2: separacao.obter. Documentação: ...'. It is not a clean single sentence, and the endpoint/doc info could be presented more cohesively. Still, it is concise and not wasteful.
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?
The tool is a simple one-parameter getter with no output schema and no annotations, so the description should at least clarify what the tool returns and how it differs from search. 'Obter Separação' is vague; it doesn't state that it returns a single separation by ID or mention any response details. The description is minimally sufficient but leaves 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?
The schema fully documents the single parameter 'idSeparacao' (100% coverage), so the parameter semantics are already covered. The description adds no extra meaning about the parameter, but the schema does. Baseline of 3 applies since the description does not need to compensate.
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 'Obter Separação' (Get Separation), a clear verb+resource combination. The endpoint 'separacao.obter' reinforces the action. However, it does not explicitly differentiate from sibling 'olist_separacao_pesquisa' or mention that it fetches by ID, though the name implies a single-record retrieval.
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 like 'olist_separacao_pesquisa'. The included documentation URL is a resource but not inline usage direction. No exclusions or alternative tool references 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?
With no annotations, the description must disclose behavioral traits. 'Atualizar informações de despacho' indicates a write operation, but it does not describe what gets overwritten, whether fields are optional, what happens to existing data, or what the response contains. No auth requirements, rate limits, or side effects are mentioned. The description adds minimal behavioral context beyond the verb.
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 main action. The first sentence states the purpose, and the second provides the endpoint and a documentation link. It avoids unnecessary fluff, though the documentation URL could arguably be moved to a separate metadata field.
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 12 parameters, no output schema, and no annotations, the description is incomplete. It does not explain expected outcomes, return values, or how this tool fits into the order-fulfillment workflow. It also lacks guidance on prerequisites or typical usage, making it insufficient for a complex mutation 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 covers 100% of parameters with descriptions, so the baseline is 3. The tool description does not add any meaning beyond the schema; it merely references the endpoint. The parameter names and schema descriptions already convey the semantics, so no additional clarification is needed.
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 the tool updates shipping information ('Atualizar informações de despacho'), which is a specific verb+resource. The endpoint name 'cadastrar.codigo.rastreamento.pedido' clarifies the exact purpose of registering tracking codes for orders, and the included documentation link adds helpful context. However, it does not explicitly distinguish itself from sibling tools like 'olist_pedido_alterar' or 'olist_nota_fiscal_cadastrar_codigo_rastreamento'.
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 only mentions the endpoint and documentation link, but does not explain prerequisites, exclusions, or scenarios where other order-update tools would be more appropriate. Usage is implied from the name and parameters but not explicitly 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not describe the return value, side effects, potential errors, or permission requirements. The verb 'Obter' (get) implies a read operation, but it is not explicitly stated whether this is safe, and no behavioral traits are disclosed beyond the endpoint and documentation link.
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 and front-loaded, conveying the purpose in the first word 'Obter' and including a documentation link for further reference. It is not verbose, but it also does not add much value beyond repeating the tool's name and providing the endpoint. The structure is efficient, though the endpoint line is somewhat redundant with the description.
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?
This is a simple get-by-ID tool with one required parameter and no output schema, but the description is still minimal. It lacks any explanation of what the tool returns, when to use it, or any behavioral details. Given that the agent must infer the tool's effect solely from the name and endpoint, the description is not complete enough for reliable selection and invocation.
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% for the single 'id' parameter, which includes a description ('Número de identificação da conta a pagar na Olist'). The tool description adds no additional meaning or context about the parameter format or usage, so the baseline score of 3 is appropriate because the schema already provides the necessary 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 states 'Obter Conta a Pagar' which clearly indicates a get operation for payable accounts. The endpoint reference 'conta.pagar.obter' reinforces the resource and action, and the tool is differentiated from sibling search tools like 'olist_contas_pagar_pesquisa' by its singular 'obter' (get) focus. However, it does not explicitly say 'retrieves a single payable account by ID,' relying on the name and schema for that inference.
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?
There is no guidance on when to use this tool versus alternatives. No mention that it is for retrieving a specific account when the ID is known, nor any distinction from the search tool or the related receivable account tool. The only context is the endpoint name, which implies usage but does not explicitly instruct the agent.
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, the description carries the burden of disclosing behavioral traits. It explicitly states the operation is mutating and requires confirmation, which is useful. However, it lacks details on side effects, reversibility, or response behavior, keeping it at a moderate level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively short but includes redundant API version and endpoint details that do not add value. It is front-loaded but could be more concise by removing these extras.
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?
The description does not explain how the account receivable is identified or what fields can be changed. Given the minimal schema and no output schema, the information is insufficient for an agent to correctly invoke the tool beyond knowing it requires confirmation.
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 fully describes the single parameter (confirmar) with 100% coverage. The description adds no additional parameter meaning beyond restating confirmar=true, so the baseline of 3 applies.
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 alters 'Conta a Receber' using the verb 'alterar', distinguishing it from sibling tools like 'incluir' (include) and 'obter' (get). However, it does not elaborate on what specific data is changed, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description only mentions that the operation alters data and requires confirmar=true, which is a prerequisite rather than a guideline for when to choose this tool over alternatives.
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?
With no annotations provided, the description must fully disclose behavior. It only states 'Search Accounts Receivable' and gives a documentation link, without mentioning that this is a read-only operation, any authentication requirements, pagination behavior, or what the response looks like. The agent cannot infer the return format or side effects.
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 a single sentence followed by a documentation URL, which is concise and front-loaded. It avoids fluff and directly states the purpose. However, it is far too brief to convey necessary behavioral or usage context, so it is not optimally structured for an MCP tool definition.
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 10 parameters, no output schema, and no annotations, the description is inadequate. It does not explain what the tool returns, how to paginate, what the date filters mean, or any limitations. The documentation link is useful but not a substitute for inline completeness. The agent would need to follow the URL to understand basic behavior.
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 description coverage is 100%, with each of the 10 parameters having a concise description in Portuguese. The tool description adds no parameter-specific information, so the baseline of 3 applies. While the schema alone defines the parameters, the description does not compensate for any missing context about how parameters interact (e.g., date ranges, mutually exclusive filters).
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 'Pesquisar Contas a Receber' (Search Accounts Receivable), which is a specific verb+resource. It identifies the endpoint and documentation link. While it does not explicitly distinguish from sibling tools like 'olist_conta_receber_obter' (get) or 'olist_contas_pagar_pesquisa' (search payable), the resource name makes it clear this is for searching accounts receivable, which is a distinct operation. However, it lacks additional scope details.
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?
There is no guidance on when to use this tool versus alternatives. It does not mention that it is for listing/filtering accounts receivable, nor does it reference sibling tools for obtaining a single record or handling payable accounts. The description only points to the endpoint and documentation, leaving the agent without decision-making 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?
With no annotations provided, the description carries the full burden for behavioral disclosure. It does state that the operation alters data and requires confirmar=true, which signals mutability, but it omits permissions, reversibility, side effects, or return behavior. For a mutation tool, this is minimal 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 very concise at three sentences and includes a documentation link. The opening 'Alterar Contato API 2.0' is slightly redundant with the tool name, but the endpoint and key requirement (confirmar=true) are front-loaded. No wasted words.
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?
The tool has a nested object parameter, no output schema, and no annotations. The description does not explain the response or return behavior, nor does it clarify the expected structure of the 'contato' object other than pointing to external docs. The documentation link helps, but the description alone is not sufficiently complete for an agent to invoke the tool confidently.
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% via parameter descriptions. The 'confirmar' parameter is well-described as a mutation confirmation flag, and the description reinforces 'exige confirmar=true'. The 'contato' parameter remains vague ('Dados do contato conforme layout') and the description does not add further details, 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.
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 with a specific verb ('Alterar') and resource ('Contato'), plus the endpoint name 'contato.alterar'. It distinguishes from siblings like olist_contato_incluir and olist_contato_obter by implying this is for changing existing contact data. However, it doesn't elaborate on what specific fields or scope are affected.
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 such as olist_contato_incluir or olist_contato_obter. The phrase 'altera dados' implies a mutation use case, but there are no exclusions, prerequisites, or comparisons to sibling tools.
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 present, so the description carries the full burden of behavioral disclosure. It only says 'Pesquisar' and gives the endpoint, but does not disclose pagination behavior, whether results are read-only, the return structure, authentication requirements, or any filtering semantics beyond what the schema provides.
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 a single concise sentence containing the API version, endpoint, and documentation URL. It is front-loaded with the key purpose, though the API version and endpoint are slightly redundant.
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?
With 8 parameters, no output schema, and no annotations, the description lacks essential context such as pagination, intended use cases, and return value expectations. The documentation link helps but does not make the description self-sufficient for an agent to invoke the 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?
The input schema already provides descriptions for all 8 parameters (100% coverage), so the baseline is 3. The description adds no parameter-level meaning beyond the endpoint and documentation link, but the schema itself is adequate for understanding each field.
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 'Pesquisar Cadastros API 2.0' and specifies the endpoint 'contatos.pesquisa', clearly identifying a contact search operation. It distinguishes from sibling tools like olist_contato_obter and olist_contato_alterar by using the 'pesquisar' verb, though 'Cadastros' is a bit generic and does not explicitly say 'contacts' except in the endpoint.
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 usage guidance is provided. The description only gives the endpoint and documentation link, with no mention of when to use this search versus alternatives like olist_contato_obter for retrieving a specific contact or olist_contato_incluir for creating one.
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?
Não há annotations, e a descrição deveria informar efeitos colaterais, permissões ou reversibilidade. Ela apenas repete que altera dados e exige confirmação, sem acrescentar detalhes relevantes de comportamento.
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 é curta e direta, com endpoint e link de documentação. Há leve redundância entre o nome da ferramenta e 'altera dados', mas sem desperdício significativo.
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?
A ferramenta não possui output schema e o objeto 'contrato' é aninhado e sem estrutura detalhada. A descrição não informa retorno, pré-condições, efeitos nem quando usar, sendo insuficiente para uso autônomo seguro.
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?
A cobertura do schema é 100%, então o baseline é 3. Porém, a descrição dos parâmetros é genérica ('Dados do contrato conforme layout') e a descrição da operação não adiciona significado além do já presente no 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?
A descrição informa explicitamente 'Alterar Contrato' e 'Esta operação altera dados', especificando verbo e recurso. Contudo, não diferencia a ferramenta de irmãs como olist_contrato_incluir ou olist_contrato_obter.
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?
Não há orientação sobre quando usar versus alternativas, nem menção a casos de exclusão. A única instrução operacional é 'exige confirmar=true', que já está embutida no schema e não explica o contexto de uso.
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?
With no annotations, the description carries the full burden of disclosing behavior. It only mentions the API endpoint and documentation URL, omitting any statement about side effects, required permissions, or return format. The verb 'obter' implies a read operation, but this is not 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 brief and front-loaded with the operation name, followed by the endpoint and docs link. No wasted words, but it is also quite minimal.
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 simple get-by-ID tool, the description provides the endpoint but omits any statement about response contents, error conditions, or usage context. It relies on the documentation link for completeness, and the lack of annotations and output schema leaves significant 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?
The input schema fully documents the single 'id' parameter (100% coverage), including its meaning as the Olist contract identifier. The description adds no parameter-specific information, so the baseline of 3 applies.
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 'Obter Contrato' (Get Contract) and identifies the API V2 endpoint, making the verb (get) and resource (contract) clear. It distinguishes from sibling tools like search/create/update, though it lacks detail on what exactly is returned.
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. It only gives the endpoint name and documentation link, with no mention of when to choose this over olist_contratos_pesquisa or other contract tools.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only supplies the endpoint name and a docs URL, but doesn't disclose return format, pagination behavior, authentication needs, or how filters are combined. For a search tool, the output and paging behavior should be described.
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 and front-loaded, stating purpose, endpoint, and documentation in three short phrases. The endpoint information is somewhat redundant with the tool name, and the docs URL provides marginal value to an AI agent, but the overall length is appropriate.
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 search tool with 8 optional filter parameters, no required parameters, no output schema, and no annotations, the description is incomplete. It fails to explain what the response looks like, how the 'pagina' pagination parameter works, or what happens when no filters are supplied. The absence of an output schema makes this gap more significant.
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. All 8 parameters (pagina, cliente, cpf_cnpj, situacao, dataFinal, idVendedor, dataInicial, nomeVendedor) have descriptions in the schema. The tool description adds no parameter-level 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'Pesquisar Contratos' (Search Contracts), with a specific verb and resource. It also identifies the API endpoint and provides a documentation link. However, it doesn't explicitly distinguish this from sibling tools like olist_contrato_adicional_pesquisa, though the 'Pesquisar' verb does separate it from get/create/update contract tools.
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 are no when/when-not conditions, no prerequisites, and no mention of sibling tools such as olist_contrato_obter or olist_contrato_alterar. The only hint is the documentation link, which doesn't count as in-description usage guidance.
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?
With no annotations provided, the description must disclose behavioral traits. It states 'Esta operação altera dados e exige confirmar=true' (this operation changes data and requires confirm=true), which signals mutation and a safety confirmation. However, it lacks details about destructiveness, reversibility, permissions, or side effects, leaving a significant transparency gap for a mutating 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 short and front-loaded with the purpose. It earns its place by including the endpoint and documentation link, though the long URL could be considered excess. It is still concise and scannable.
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 a simple 3-parameter schema, the tool is a mutation with no annotations and no output schema. The description only covers basic purpose and the confirm flag, but omits usage context, potential consequences, and any guidance on valid inputs (like situation codes). It feels incomplete for safe invocation.
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 extra parameter meaning beyond what the schema already provides; it only repeats the confirm=true requirement, which is already documented as a boolean const 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: 'Alterar situação da ação do assunto do CRM API 2.0' (change status of CRM action), with a specific verb and resource. It also names the exact endpoint, which helps distinguish the operation, though it doesn't explicitly differentiate from siblings like 'alterar_estagio_assunto'.
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 only mentions that the operation alters data and requires confirm=true, but does not explain when this is the right choice among the many CRM/sibling tools. This is a missed opportunity given similar-sounding tools exist.
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?
Without annotations, the description carries the full burden. It discloses that the operation 'altera dados' (changes data) and requires confirmar=true, but this is largely redundant with the schema's confirmar parameter description ('operação mutável'). No additional behavioral context is provided, such as side effects, reversibility, permissions, or expected response.
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 tool's purpose. The inclusion of the endpoint and docs link is useful, though the endpoint line slightly duplicates the tool name. No wasted words.
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?
For a simple mutation tool with 2 fully described parameters and a docs link, the description is minimally sufficient. However, it lacks any explanation of what 'assunto' represents, the expected return format, or error behavior. The docs link mitigates but does not replace this missing 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 description coverage is 100% for both parameters, so the baseline is 3. The description adds nothing about the parameters themselves; it only references the endpoint and mutation requirement, which does not compensate or enhance parameter understanding.
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 the operation verb 'Incluir' (include) and resource 'Assunto' (subject), plus the endpoint 'crm.incluir.assunto' and a docs link. This clearly indicates a CRM subject creation tool, though it does not explicitly differentiate it from sibling tools like olist_crm_incluir_acao_assunto.
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 only states that it alters data and requires confirmar=true, without any contextual markers such as 'use this to create a new CRM subject' or 'if you need to...'.
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 present, so the description must disclose behavioral effects. It only states the action without mentioning side effects (e.g., status changes), required permissions, or reversibility, leaving the agent without awareness of consequences.
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 front-loaded with the primary purpose. It includes useful endpoint and documentation references without unnecessary prose, though the endpoint is partially redundant with the tool name.
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?
As a mutation tool with no annotations or output schema, the description fails to explain behavioral outcomes, prerequisites, or return values. The provided documentation link helps but does not substitute for an inline behavioral summary.
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 already provides 100% parameter coverage, describing idObjetos and tipoObjetos clearly. The description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Enviar objetos para a expedição' (send objects to expedition), identifying a specific verb and resource. It also provides the API endpoint. However, it does not explicitly differentiate this from sibling expedition tools, though the action of 'liberar' (releasing) 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 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 simply states the action and endpoint without mentioning prerequisites, use cases, or excluded scenarios.
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 present, so the description carries the full burden of behavioral disclosure. It only says 'get shipments' and provides the endpoint; it does not describe the return format, pagination, authentication needs, or side effects, even though it is a read operation.
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 verb 'Obter'. However, the 'API 2.0' and endpoint name are somewhat redundant, and the documentation link could be considered a substitute for inline guidance rather than a substitute for behavior.
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?
With no output schema and no annotations, the description should clarify what data is returned and how the optional parameters relate (e.g., object-based vs. expedition-based lookup). It does not; it relies entirely on an external docs link, leaving the agent without enough context to fully understand the tool's behavior.
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 already provides 100% coverage with clear descriptions for idObjeto, tipoObjeto, and idExpedicao. The tool description adds no additional parameter-level meaning, so it stays at the baseline for a fully documented 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 states 'Obter expedições' (get shipments) and names the API endpoint 'expedicao.obter', giving a clear verb and resource. It is distinct from sibling tools like olist_expedicao_pesquisa, but it does not explicitly explain that this is for retrieving a specific shipment by ID/object rather than listing/searching.
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 like olist_expedicao_pesquisa or olist_expedicao_obter_agrupamento_impressao. The description only gives an endpoint name and a documentation link, without mentioning use cases, prerequisites, or exclusions.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, what data it returns, whether it has side effects, or any prerequisites. The endpoint string and documentation link add little 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 concise and front-loaded with the purpose. The repeated endpoint information and documentation link are somewhat redundant but do not significantly bloatt the text.
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?
This is a single-parameter tool with no output schema and no annotations, so the description should explain what the printing grouping contains or how it is returned. It does not, leaving a significant gap for an agent deciding whether and how to invoke it 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?
The input schema provides full coverage for the single parameter 'idAgrupamento' with a description ('ID do agrupamento na Olist'), so the baseline is 3. The description adds no additional parameter context beyond what the schema already contains.
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 a specific action ('Obter agrupamento para impressão' - get grouping for printing) and names the API endpoint. It is clear about the resource and operation, though it does not explicitly differentiate itself from similar expedition tools like olist_expedicao_obter_etiquetas_impressao.
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. It only provides the endpoint and a documentation link, leaving the agent to infer the appropriate context from the name alone.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It only mentions 'obter' (retrieve) and the API endpoint, but does not describe the output format, whether it is read-only, any side effects, or authentication requirements. This is a significant gap.
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 and front-loaded with the purpose. However, the documentation URL and API endpoint are not directly useful for an AI agent, though they do not significantly bloat the text. It earns a 4 rather than 5.
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 no output schema and minimal annotations, the description is insufficient. It does not explain what the labels look like, how to invoke the print, or the relationship to other expedition tools. The description is only a single purpose statement, lacking essential context for correct 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?
The input schema already provides descriptions for both parameters (idExpedicao and idAgrupamento) with 100% coverage. The description adds no additional parameter context, so it remains at the baseline of 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 retrieves labels for printing ('Obter etiquetas para impressão'), which is a specific action and resource. However, it does not explicitly differentiate from sibling tools like 'olist_expedicao_obter_agrupamento_impressao', so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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, no prerequisites, and no context such as requiring an expedition ID or grouping ID. The documentation link is not actionable for an AI agent.
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 provides no behavioral details beyond the fact that it is a search operation. It does not state whether it is read-only, any pagination behavior, or response format. Since there are no annotations, the description carries the full burden and fails to disclose important traits.
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 three short fragments, but it is somewhat sparse. It front-loads the core purpose, then adds endpoint and documentation, which is acceptable but not particularly structured.
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?
The tool has no annotations and no output schema, and the description does not explain return values, filtering semantics, or relationship to other expedition tools. The documentation link may help, but within the description context, it is incomplete for an agent to understand full capabilities.
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?
All five parameters are documented in the input schema with descriptions, so baseline is 3. The description itself adds no parameter-level context beyond what the schema already provides.
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 that this tool searches 'agrupamentos' (groupings) via the API V2 endpoint, giving a specific verb and resource. It does not explicitly differentiate it from sibling tools like olist_expedicao_pesquisa or olist_expedicao_obter, but the resource 'agrupamentos' is specific.
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?
There is no guidance on when to use this tool versus alternatives such as olist_expedicao_pesquisa or olist_expedicao_obter. The only additional information is a documentation link, which is not in-line guidance.
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 behavioral disclosure burden. It explicitly states the operation alters data and requires confirmar=true, which is valuable. However, it does not describe the actual effect (creating a tag group), the response format, permissions, or side effects. Minimal transparency beyond the mutation warning.
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 that front-load the purpose and include a critical behavioral requirement. The documentation URL is useful and the text contains no fluff, though 'API 2.0' and 'API V2' are slightly redundant. Overall, every sentence 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?
The tool has a nested object parameter ('grupo') described only as 'conforme layout' without any layout details, and there is no output schema. The description does not explain what the operation returns, what the expected structure of 'grupo' is, or any prerequisites. For a mutation tool with opaque parameters and no output schema, this is insufficient.
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% parameter documentation with descriptions for 'grupo' and 'confirmar'. The description does not add meaningful parameter semantics beyond the schema, merely restating the confirmar requirement. With full schema coverage, the baseline of 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 'Incluir Grupo de Tags' (Include Tag Group) and specifies the endpoint 'grupo.tag.incluir', indicating a create operation. It does not explicitly distinguish from sibling tools like olist_grupo_tag_alterar or olist_grupo_tag_pesquisa, but the verb 'incluir' and resource make the purpose fairly clear.
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 when to create a tag group as opposed to altering or searching, and it lacks any 'use this when...' context. The only note, 'Esta operação altera dados e exige confirmar=true', is a safety warning, not a usage guideline.
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?
With no annotations provided, the description carries the burden of behavioral disclosure. It states the tool updates dispatch information, but does not disclose any side effects, required nota fiscal state, whether existing tracking codes are overwritten, or what response to expect. The generic 'atualizar informações de despacho' leaves key behavioral details undefined.
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 two sentences that front-load the action ('Atualizar informações de despacho') and provide a documentation link. However, it is slightly redundant by stating 'API 2.0' and then repeating the full endpoint name with the same 'API V2' qualifier, which could be streamlined.
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?
The tool has no annotations, no output schema, and a single nested object parameter that is only vaguely described as 'conforme layout'. The description lacks information about return values, preconditions, or operational behavior. It relies on an external documentation URL, which is not accessible to the agent at invocation time, making the description insufficient for an agent to confidently invoke the 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 schema covers 100% of the single parameter with a description ('Dados do despacho conforme layout'), which gives only a vague reference to a layout. The tool description adds no further semantic detail about the parameter's structure or expected fields. Since schema coverage is high, the baseline is 3, and the description does not meaningfully enhance it.
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 'Atualizar informações de despacho' (update shipping information), which clearly identifies the action and resource. It also provides the exact API endpoint name. However, it does not explicitly mention 'cadastrar código de rastreamento' (register tracking code) in the description, and it does not distinguish itself from the sibling tool 'olist_cadastrar_codigo_rastreamento_pedido', which appears to serve a similar purpose for orders.
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?
There is no guidance on when to use this tool versus alternatives. The description only provides the endpoint name and a documentation link, with no mention of prerequisites, use cases, or when to choose this over the similar sibling tool for registering tracking codes on orders.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'obter' (get) and provides an endpoint and a documentation link, without mentioning read-only behavior, error handling, authentication, or output format. The read operation is implicit from the verb but not explicitly disclosed.
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 few words and no verbosity. It front-loads the main action but the 'Endpoint API V2' line is largely redundant with the tool name, and the documentation link is helpful but not a substitute for a structured description. Overall efficient, though not well-structured.
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 get-by-id tool with no output schema and no annotations, the description lacks essential context such as return values, error scenarios, or prerequisites. The documentation link outsources information that should be in the description, leaving the agent under-equipped to invoke the tool correctly without external help.
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 already provides 100% coverage for the single 'id' parameter with a clear description ('Número de identificação da nota fiscal na Olist'). The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate per the rubric.
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 the tool obtains a Nota Fiscal (invoice) via API 2.0, which is a clear verb+resource combination. However, it does not explicitly distinguish this from sibling tools like olist_nota_fiscal_obter_xml or olist_nota_fiscal_obter_link, though the tool name and 'obter' hint at a generic retrieval operation.
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 that it retrieves a single invoice by ID, nor does it suggest using olist_notas_fiscais_pesquisa for searching or olist_nota_fiscal_obter_xml for XML retrieval. The only context is an external documentation link.
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?
With no annotations, the description carries the full burden. It only provides the endpoint and documentation URL, but does not describe what the tool returns (e.g., a URL), any required permissions, error behavior, or whether the link is temporary. This is minimal disclosure for a tool with no structured safety hints.
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 tool's purpose. The endpoint and documentation link add useful technical context without being verbose. It is appropriately sized for a simple one-parameter tool, though it could be slightly more informative.
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's simplicity, the description is still incomplete. There is no output schema, and the description does not explain what the response looks like (e.g., a link) or how the link should be used. The description plus schema provide only a bare minimum, lacking essential contextual details like return value and typical usage scenarios.
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 covers 100% of parameters, and the 'id' parameter has a clear description ('Número de identificação da nota fiscal na Olist'). The description adds no additional parameter context, but per guidelines, the schema does the heavy lifting, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Obter Link da Nota Fiscal' (Get Invoice Link), a specific verb and resource. It distinguishes from sibling tools like olist_nota_fiscal_obter (get invoice) and olist_nota_fiscal_obter_xml (get XML) by focusing on obtaining the link. However, it adds little beyond the tool name itself.
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. It does not mention that this tool is for retrieving a link specifically, nor does it exclude cases where one should use olist_nota_fiscal_obter or olist_nota_fiscal_obter_xml instead. The usage context is entirely implied.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states that the tool obtains XML and gives the endpoint. It does not describe what the XML contains, whether authentication is required, what errors may occur, or whether this is a safe read-only operation beyond the implied 'obter' (get).
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 two short sentences that state the purpose and provide the endpoint and documentation link. No unnecessary words are used, and the structure front-loads 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?
For a simple single-parameter retrieval tool with no output schema, the description gives the essential purpose and a documentation URL. However, it lacks information about the return format or any behavioral details, which would have made it more complete given the absence of an output 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 coverage is 100%: the only parameter 'id' is described as 'Número de identificação da nota fiscal na Olist'. The tool description adds no further semantic detail about the parameter, so it relies entirely on the schema, which is adequate for a single simple identifier.
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 function: 'Obter XML da Nota Fiscal API 2.0' (Get the Nota Fiscal XML from API 2.0), which specifies the verb and resource. It distinguishes itself from sibling tools like olist_nota_fiscal_obter and olist_nota_fiscal_obter_link by explicitly targeting XML retrieval, though it does not explicitly compare itself to those alternatives.
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 such as olist_nota_fiscal_obter or olist_nota_fiscal_obter_link. It only mentions the endpoint and documentation URL, leaving the agent to infer usage context from the tool name and schema.
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?
With no annotations, the description must carry the full behavioral burden, but it only states the endpoint and provides a docs link. It does not disclose whether the operation is read-only, any side effects, permission requirements, or the return format. The term 'Consultar' implies a read operation but this is not 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 very short, consisting of a single sentence and a documentation link. It is front-loaded with the purpose and wastes no words, but the extreme brevity leaves out important context, preventing a perfect score.
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 lack of annotations and output schema, the description is incomplete. It does not explain what the response contains, any preconditions, or how this consult operation relates to other service-note tools. The documentation link is helpful but the description should be more self-contained.
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%, as both 'id' and 'enviarEmail' have descriptive text. The description does not add any additional parameter meaning beyond the schema, so it meets the baseline but provides no extra value.
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 action 'Consultar' (query) and the resource 'NFS-e' (service invoice), and identifies the specific API endpoint. However, it does not explicitly differentiate from sibling tools like 'olist_nota_servico_obter' or 'olist_notas_servico_pesquisa', so it lacks strong sibling distinction.
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 such as 'olist_nota_servico_obter' or 'olist_notas_servico_pesquisa'. There is no mention of prerequisites, contextual triggers, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only provides the endpoint and a documentation link. It does not state whether the operation is read-only, what the response contains, or any side effects. This lack of behavioral information is a significant gap for an agent deciding whether to invoke the 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 appropriately sized and front-loaded with the main purpose. It consists of a single sentence plus endpoint and documentation reference, containing no redundant content. However, the documentation URL could be considered slightly extraneous in a description, though it adds value.
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 absence of an output schema and annotations, the description should offer more context about return values or usage scenarios. It only identifies the endpoint and documentation link, which is insufficient for an agent to fully understand the tool's behavior and expected 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?
The input schema has 100% coverage for the single 'id' parameter, including a clear description of what it represents. The tool description adds no extra parameter semantics beyond the schema, so the baseline score of 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's purpose with a specific verb and resource: 'Obter Nota de Serviço' (Get Service Note). It also identifies the API endpoint and provides documentation, making the intent unambiguous. However, it does not explicitly distinguish itself from sibling tools like olist_nota_servico_consultar, though the use of 'obter' and the 'id' parameter suggest direct retrieval by ID.
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 such as olist_notas_servico_pesquisa or olist_nota_servico_consultar. It does not mention appropriate use cases, prerequisites, or exclusions, leaving the agent to infer usage solely from the tool name and sibling 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?
With no annotations, the description carries the full burden of behavioral disclosure, but it only says 'search invoices' and provides an endpoint. It does not mention read-only nature, pagination behavior, response format, or any caveats. The documentation link is an external resource, not in the description itself.
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 one sentence plus a link. It front-loads the purpose, then gives endpoint and docs. The repetition of 'API 2.0' and 'API V2' is slightly redundant, but overall it's efficient.
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 12 parameters and no output schema, the description is minimal. It doesn't explain how filters interact, the meaning of pagination (e.g., 'pagina'), or what the response looks like. The documentation link helps, but the description itself is incomplete for a tool with this complexity.
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 12 parameters with descriptions. The description adds no additional meaning beyond stating the endpoint, so the baseline of 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 searches for invoices ('Pesquisar Notas Fiscais'), with a specific verb and resource. It also mentions API 2.0 and the endpoint, but does not explicitly differentiate from sibling tools like 'olist_notas_servico_pesquisa' (service invoices) or 'olist_nota_fiscal_obter' (get single invoice), so it misses the full distinction.
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 simply states what it does and includes a documentation link, but lacks any context about suitable scenarios, exclusions, or prerequisites.
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?
With no annotations, the description carries the full burden for behavioral disclosure. It implies a read-only search operation but does not explicitly state the nature of the operation, pagination behavior, authentication needs, or potential side effects. The endpoint and documentation link do not add 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 very concise, leading with the key phrase 'Pesquisar Produtos', followed by the endpoint and documentation link. It avoids verbosity, though it is composed of fragments rather than complete sentences, slightly reducing structural quality.
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?
The description omits important context: it does not explain what the search returns, how pagination works, or how it differs from sibling tools like 'olist_produtos_pesquisa'. The documentation link is a useful pointer but does not make the description self-contained. Given no output schema or annotations, the description is incomplete.
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 (e.g., 'Número da página', 'Nome ou código...'). The description adds no additional parameter-level detail, so the baseline score of 3 applies because the schema already handles parameter 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 the action 'Pesquisar Produtos' (search products) and provides the API endpoint, making the primary purpose apparent. However, it does not explicitly distinguish this PDV-specific product search from the sibling tool 'olist_produtos_pesquisa', though the 'PDV' prefix implies a narrower 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?
No guidance is provided on when to use this tool versus the general product search tool or other alternatives. The description lacks context about prerequisites, use cases, or scenarios where this tool should be preferred.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does state that the operation 'altera dados' (changes data) and requires 'confirmar=true', which is a safety-related behavior. However, it does not disclose potential side effects, reversibility, permissions required, or what specific changes are made. This is minimal coverage for a mutation 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 concise, consisting of three short sentences that state the operation name, endpoint, documentation link, and core behavior. It is well-structured and front-loaded with the essential action. Slight improvement could be made by including the object of the alteration (order) more explicitly, but overall it is efficient.
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 only 2 parameters, one is a nested object ('id') with unrestricted properties (additionalProperties: {}), and there is no output schema. The description does not explain how to construct the 'id' object, what the response format is, or error scenarios. This leaves significant gaps for an AI agent to invoke the 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%, so both parameters are already documented with meaningful descriptions. The description only reiterates that 'confirmar=true' is required, which adds no new information beyond the schema. It does not help clarify the structure of the 'id' object parameter, which remains vague.
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 operation is 'Alterar Pedido' (change order) and 'altera dados' (changes data), identifying it as a mutation tool for orders. This distinguishes it from sibling tools like olist_pedido_incluir (create) and olist_pedido_obter (read). However, it does not explicitly mention 'sale order' in the description text, relying on the parameter description for that context.
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 prerequisites, comparison with related tools, or typical scenarios. The only usage hint is the implicit need for an existing order ID and confirmation, but no explicit direction is 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?
With no annotations provided, the description carries the full burden. It does state the operation 'altera dados' (changes data) and requires confirmar=true, providing some transparency about mutation. However, it omits important behavioral details such as irreversibility, side effects on financial records, required permissions, or response behavior. This is insufficient for a mutation tool with no annotation support.
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 front-loaded with the purpose ('Estornar Contas do Pedido'). The endpoint sentence is somewhat redundant with the tool name, and the documentation URL is useful but lengthy. Overall, it is concise with minimal waste, though the redundancy slightly reduces efficiency.
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 tool is simple with only 2 parameters, no output schema, and no annotations. The description gives the essential purpose and the confirmation requirement, which covers the minimal invocation requirements. However, it lacks context about the business effect of the reversal, any prerequisites (e.g., order status), and whether the operation is reversible, leaving gaps for a complete 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?
Schema description coverage is 100%, with both id and confirmar fully described. The description reinforces the mutable nature and confirmar=true, but adds little beyond the schema. The baseline for high coverage is 3, and the description does not compensate with additional parameter 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 the action ('Estornar Contas do Pedido' - reverse order accounts) and identifies the API V2 endpoint. The verb-resource combination distinguishes it from sibling tools like olist_pedido_lancar_contas and olist_pedido_estornar_estoque, though it does not explicitly describe what 'estornar contas' entails in business terms.
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 mention that the operation requires confirmar=true, which is a prerequisite, but does not state the context (e.g., when an order's accounts have been posted and need reversal) or specify exclusions. Sibling tools like olist_pedido_lancar_contas are not referenced.
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 the operation mutates data and requires confirmar=true, which is important given no annotations exist. However, it does not describe side effects such as changes to stock levels or order status, or whether the operation is reversible. The documentation link is a useful pointer but not a substitute for in-description 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 concise and includes the endpoint and documentation link without unnecessary fluff. It is front-loaded with the operation name but does not waste words, though the title/endpoint repetition is slightly redundant.
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?
For a simple two-parameter tool with no output schema, the description provides the endpoint, a mutation warning, and a docs link. However, it lacks a clear explanation of what 'lançar estoque' accomplishes or what the agent should expect after invocation, leaving a moderate gap in 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?
The input schema fully describes both parameters (id as the order ID on Olist, confirmar as a boolean const true). The description only reiterates the confirmar requirement, adding no additional semantic meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description restates the tool name ('Lançar Estoque do Pedido') without defining the operation in domain terms. It adds that the operation alters data, but the specific effect on stock or order status is not explained, making the purpose somewhat vague.
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. It does not mention that this is the opposite of 'olist_pedido_estornar_estoque' or any prerequisites, leaving the agent to infer usage from the name alone.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool 'obter' (gets) a product, implying a read-only operation, but does not disclose return format, error behavior, authentication requirements, or side effects. The documentation link is referenced but not inline, so the agent is left without 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one short phrase identifying the operation, the API version, and a documentation link. It is front-loaded with the core purpose ('Obter Produto') and contains no fluff or redundant information. Every sentence earns its place, making it an efficient and well-structured description.
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 the low complexity (one parameter, no output schema, no annotations), the description is incomplete. It does not state what the tool returns (e.g., product details) or provide any direct context about the response. The documentation link is helpful but not self-contained, and the agent would need external access to understand the full behavior. This is insufficient for a get operation that needs to be understood without an output 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?
The input schema already describes the sole parameter 'id' with a clear Portuguese description ('Número de identificação do produto na Olist'), so schema coverage is 100%. The tool description does not add any extra meaning about the parameter beyond what the schema provides, so the baseline score of 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 'Obter Produto' (Get Product), identifying a specific verb and resource, and distinguishes it from sibling tools like olist_produtos_pesquisa (search), olist_produto_incluir (create), and olist_produto_obter_estoque (get stock). However, it relies on the tool name to convey the full action and does not explicitly mention fetching by ID or the response payload, so it is clear but not fully elaborated.
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 offers no guidance on when to use this tool versus alternatives. It does not mention that this is for fetching a single product by ID, nor does it contrast with olist_produtos_pesquisa for searching. The only context is the endpoint name and a documentation link, leaving the agent to infer the use case from the schema and sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/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, but it only repeats the endpoint and links to documentation. It does not mention whether the operation is read-only, what happens if the product is not found, any authentication requirements, or what the response contains.
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 three short sentences: purpose, endpoint, and documentation link. It is front-loaded and free of unnecessary elaboration, though there is minor redundancy between the name and the endpoint statement.
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?
This is a simple tool with one parameter and no output schema, but the description does not explain what the tool returns (e.g., stock quantity, warehouse breakdown) or how the 'id' should be interpreted. The documentation link provides some external context, but the description alone is incomplete for an agent to fully understand the tool's behavior.
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% (only 'id' parameter with a clear description), so the schema already documents the parameter fully. The tool description adds no additional meaning beyond what the schema provides, matching the baseline for high coverage.
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 'Obter Estoque Produto' (Get Product Stock) and the exact API endpoint, making the tool's purpose specific and unambiguous. It distinguishes itself from sibling tools like olist_produto_atualizar_estoque (update stock) and olist_produto_obter (get product details).
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 such as olist_produto_atualizar_estoque or olist_produtos_pesquisa. It merely states the endpoint and documentation link without any situational context or exclusions.
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, leaving the description as the sole source of behavioral context. The description mentions API 2.0 and an endpoint but does not disclose what the structure contains, whether it is read-only (though 'obter' implies retrieval), or any quirks. The documentation link is a pointer, not actual 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 brief and front-loaded with the purpose, but it is fragmented into three short segments (name, endpoint, documentation link). It is not overly verbose, though the endpoint string repeats the tool name and the doc link may not add immediate value.
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?
With one parameter, no output schema, and no annotations, the description should explain what the product structure is, what the response looks like, or when to use this tool. It provides none of that, leaving the agent without essential context beyond the tool's name.
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 one parameter 'id' with a clear description ('Número de identificação do produto na Olist'), so schema coverage is 100%. The description does not add any additional meaning to the parameter, but the schema already provides sufficient information.
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: 'Obter Estrutura do Produto' (Get Product Structure), which is a specific verb+resource combination. It also names the API endpoint, but it does not explicitly differentiate from sibling tools like 'olist_produto_obter' which also retrieves product data.
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?
There is no guidance on when to use this tool versus alternatives. The description only restates the tool's name and provides a documentation link, with no context about use cases, exclusions, or prerequisites.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Pesquisar Tag' (search tag), which is a minimal indicator, but it does not disclose read-only nature, return format, pagination behavior, or potential side effects. The schema parameters cover some details, but the description itself adds no 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 very concise and front-loaded with the action, and the documentation link is useful. However, it is so terse that it sacrifices substance; still, it has no wasted words, so it scores above average.
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 simple search tool with no output schema, the description should explain what the search returns and how it relates to tag groups. The parameter descriptions hint at group tags, but the description does not clarify the tool's role among siblings. With no output schema and no annotations, this is incomplete.
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% for all three parameters, so the schema already documents their meaning (page number, group ID, search text). The description adds no additional parameter context, so the baseline score of 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 a clear verb ('Pesquisar') and resource ('Tag'), and the endpoint name reinforces the action. However, it does not explicitly differentiate from sibling olist_grupo_tag_pesquisa or describe what kind of tags are searched, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 like olist_grupo_tag_pesquisa. The description merely gives an endpoint and a documentation link, with no usage context, prerequisites, or exclusions.
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?
With no annotations, the description carries the full burden of behavioral disclosure, but it only says 'list' and gives an endpoint. It does not say whether this is read-only, what the response looks like, or any limitations, making it minimally transparent.
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 a single sentence that concisely states the purpose and includes a documentation link. It is efficient with no filler, though the technical endpoint string adds some clutter.
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?
The description is too sparse for the tool's context: it doesn't explain what 'assunto' refers to, what the list contains, or whether it returns all stages or stages per subject. The documentation link is helpful, but the description alone is incomplete for an agent deciding when to call it.
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 the schema is empty, so there is nothing to explain in the description. The baseline of 4 applies because no parameter information is needed.
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 de Estágios do CRM' and identifies the endpoint, so an agent can see this tool lists CRM stages. It is distinguished from sibling tools focused on other CRM entities, though it doesn't explicitly mention 'assunto' as part of the resource.
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?
There is no guidance on when to use this tool versus alternatives. The description provides only the endpoint and documentation link, leaving the agent to infer its appropriate use from the 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?
With no annotations, the description carries the full burden. It states the operation alters data and requires confirmar=true, but this is redundant with the schema's confirmar parameter description ('operação mutável'). No additional behavioral context like side effects, permissions, or response behavior is disclosed.
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 sentences, front-loading the purpose and endpoint. The documentation link is useful, though the title and endpoint are somewhat repetitive. Overall, it is efficient and well-structured.
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?
With no output schema and no annotations, the description must provide complete context. It fails to explain the structure of 'acao', how to obtain valid values, what the response looks like, or how this tool fits with related CRM operations. The documentation link is helpful but does not compensate for the lack of inline detail.
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 both 'acao' and 'confirmar' already described clearly. The tool description adds no further meaning beyond what the schema provides, so the 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 'Incluir Ação no Assunto do CRM' (Include Action in CRM Subject) and provides the API endpoint, clearly identifying the action and resource. This distinguishes it from sibling tools like olist_crm_incluir_assunto by specifying this is for adding an action to a subject.
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 given on when to use this tool versus alternatives such as olist_crm_incluir_assunto or olist_crm_alterar_situacao_acao. The mention of 'altera dados e exige confirmar=true' is a prerequisite for execution rather than a usage scenario, and no exclusions or alternative conditions are provided.
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?
With no annotations, the description carries the full burden of behavioral disclosure, but it only says 'Pesquisar' and gives an endpoint. It does not mention whether results are paginated, what fields are returned, whether a request is read-only, or any side effects. There is no output schema, and the description adds minimal 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 short and front-loaded with the main purpose in the first sentence. The endpoint and documentation link are useful, though there is slight redundancy between 'API 2.0' and 'API V2'. It is concise without being padded, but not maximally polished.
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 10 optional parameters, no annotations, and no output schema, the description is too sparse. It tells the agent what the tool does and where to find docs, but does not explain the return structure, pagination behavior, or any operational details needed to use it reliably without external documentation.
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 covers 100% of parameters with descriptive names and explanations, so the baseline is 3. The description adds no parameter semantics beyond the endpoint name, nor does it clarify relationships between parameters or expected values. The schema already does the heavy lifting.
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 with a specific verb ('Pesquisar') and resource ('Assuntos do CRM'), and the endpoint name 'crm.pesquisa' reinforces its search nature. This distinguishes it from sibling tools like 'olist_crm_obter_assunto' and 'olist_crm_incluir_assunto'.
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 only states what it does and gives an endpoint and documentation link, but no context for when a search over 'assuntos' is appropriate, nor any exclusions or comparisons to sibling search tools.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It indicates a search operation via the verb 'Pesquisar' and provides a documentation link, but it does not explain return format, read-only guarantees, pagination, or the effect of the optional 'situacao' filter beyond the schema. This is minimal 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose and includes a useful endpoint and documentation link. No unnecessary words or repetition.
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?
For a tool with one optional parameter and no output schema, the description provides the essential purpose and endpoint, but it lacks details about return values or expected behavior. It is minimally viable but leaves gaps for an agent deciding on invocation.
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% (one parameter 'situacao' with a clear Portuguese description), so the schema provides full parameter meaning. The description adds no additional parameter semantics, matching the baseline for high schema coverage.
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 'Pesquisar Formas de Recebimento' (Search Payment Methods), identifying the verb and resource. It also provides the exact API endpoint, which reinforces the purpose. However, it does not explicitly differentiate this search tool from sibling 'pesquisa' tools beyond the resource name.
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, nor any mention of prerequisites or filters. The description simply states the search action without context for selection.
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 explicitly states 'Esta operação altera dados' and 'exige confirmar=true', which transparently warns about the mutating nature and the confirmation requirement. However, it does not elaborate on side effects, reversibility, or permissions, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three sentences that front-load the purpose, provide a documentation link, and state the key mutation safety warning. It avoids fluff and is appropriately sized, though the first two sentences ('Emitir Nota Fiscal API 2.0' and 'Endpoint API V2: nota.fiscal.emitir') are slightly redundant.
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 5-parameter mutation tool with no output schema and no annotations, the description is insufficiently complete. It lacks workflow context, prerequisites, expected outcomes, or guidance on when this operation should be used relative to other invoice-related tools. The documentation link helps but does not substitute for inline 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?
The input schema has 100% description coverage for all 5 parameters, so the baseline is 3. The description does not add parameter-specific meaning beyond the schema; it only reiterates the confirmar requirement, which is already enforced by the schema's const and required fields.
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 function: 'Emitir Nota Fiscal API 2.0' (issue invoice API 2.0). It identifies the specific endpoint and resource, making the purpose unambiguous. However, it does not explicitly differentiate this 'emitir' operation from sibling invoice tools like 'incluir' or 'gerar_nota_fiscal_pedido', so it lacks explicit sibling distinction.
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?
There is no guidance on when to use this tool versus alternatives. The description mentions that the operation alters data and requires confirm=true, which is a safety prerequisite but not a usage guideline. No alternatives or contextual triggers are 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 burden. It does disclose that the operation mutates data and requires confirmar=true, which is important safety-relevant behavior. Yet it omits other behavioral context such as permissions, side effects, reversibility, or what happens upon validation failure.
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 and front-loaded, but 'API 2.0' and 'Endpoint API V2: nota.fiscal.incluir' are somewhat redundant. The documentation link is useful and there is no irrelevant filler, keeping it reasonably efficient.
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?
The tool has a flexible nested 'nota' object and no output schema, so the description should clarify expected payload structure and return behavior. It only points to external documentation and does not explain preValidarNota semantics or success/error outcomes, leaving significant gaps 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?
All parameters have schema descriptions, so the baseline is 3. The description adds no parameter-level detail beyond the schema; the 'nota' nested object remains vaguely described as 'conforme layout' in both the description and 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 verb and resource ('Incluir Nota Fiscal') and provides the API endpoint, making the basic purpose unambiguous. However, it does not differentiate this tool from sibling tools such as olist_nota_fiscal_emitir or olist_nota_fiscal_consumidor_incluir.
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?
There is no guidance on when to use this tool versus alternatives. The description only mentions the endpoint and documentation link, without explaining use cases, prerequisites, or exclusions among the many sibling nota fiscal operations.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. The verb 'Obter' implies a read operation, but it does not specify return format, potential errors, authentication requirements, or any side effects. The documentation link is not a substitute for inline 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: a single sentence plus a documentation URL. It is front-loaded with the purpose and endpoint, and the URL may provide additional reference. No unnecessary wording, though it could be slightly more informative 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 being a simple tool with one parameter and no output schema, the description does not explain what the response contains or how it differs from other order retrieval tools. The documentation link could fill gaps, but the description itself is not complete enough for an agent to confidently invoke the tool without external resources.
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 one parameter 'id' with a description, giving 100% coverage. The tool description adds no additional meaning about the parameter beyond what the schema already provides, so the baseline of 3 applies.
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 'Obter Pedido' (Get Order) with the 'PDV' prefix, indicating it retrieves a PDV (point-of-sale) order. This distinguishes it from sibling tools like 'olist_pedido_obter' which handles regular orders. The endpoint name 'pdv.pedido.obter' reinforces the specific resource.
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 only mentions the endpoint and a documentation link. There is no mention of prerequisites, whether this is for single order retrieval by ID, or when to prefer other order-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, the description carries the burden of disclosure. It does explicitly state 'Esta operação altera dados' and requires confirmar=true, which is useful. But it omits other behavioral aspects like permissions, side effects, or response format.
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 tool's purpose, endpoint, and critical mutation warning. The documentation URL adds value, though it could be considered non-essential; overall it is efficient with no wasted words.
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?
The produto parameter is an opaque nested object with no structured properties, and there is no output schema. The description does not explain how to build the payload or what the operation returns, relying instead on an external documentation link. This is insufficient for a mutating tool with an undefined nested object.
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% and both parameters have basic descriptions, so baseline 3 applies. The description adds no additional parameter meaning beyond the confirmar=true requirement already present in the schema, and the 'produto' object remains vaguely defined as 'conforme layout'.
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 identifies the operation as 'Incluir Produto' (include product) and names the API 2.0 endpoint, which distinguishes it from sibling tools like alterar/obter. However, it does not explicitly contrast it with olist_produto_alterar or state 'create a new product' in plain terms.
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 about when to use this tool versus alternatives such as olist_produto_alterar or olist_produtos_pesquisa. The description only mentions the endpoint and a mutation warning, leaving the agent to infer the use case.
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, the description carries the behavioral burden. It explicitly states 'Esta operação altera dados' and 'exige confirmar=true', disclosing mutation and confirmation requirements. However, it does not detail side effects, reversibility, or response behavior, and relies on an external documentation link.
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 and front-loaded with the core purpose. It includes a documentation URL and a mutation warning in a few short sentences, with no wasteful filler. The endpoint and documentation lines are slightly redundant but the overall structure is efficient.
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 mutation tool with no annotations, no output schema, and a free-form nested object (tag), the description is insufficient. It does not describe the expected layout of the tag object or the response format, relying solely on an external link. An agent cannot confidently construct the required parameters from the description alone.
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 descriptions for both parameters. The description adds no extra meaning beyond the schema; the confirmar requirement is already encoded via const:true. The tag object's internal structure is left vague with 'conforme layout' and a doc link, offering no additional 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 'Incluir Tag' clearly identifies the action (include/create) and resource (Tag), distinguishing it from siblings like olist_tag_pesquisa and olist_tag_alterar. It also specifies the API version and endpoint, but lacks a detailed scope of what the tag creation entails.
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 only operational note is the confirmar=true requirement, which is a prerequisite rather than usage context. There are no exclusions or recommendations for alternative 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, the description carries the burden of disclosing mutating behavior. It explicitly states 'Esta operação altera dados e exige confirmar=true', which is useful safety information. However, this partly duplicates the schema's const=true on confirmar, and it omits other behavioral aspects like idempotency, reversibility, or side effects beyond data mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but contains redundancy: 'Incluir Conta a Pagar API 2.0' and 'Endpoint API V2: conta.pagar.incluir' convey overlapping information. The documentation link and behavioral warning are useful, but the structure could be tighter.
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?
This tool has a nested 'conta' object with no structural schema, and no output schema. The description does not explain the expected payload layout or return value, instead pointing to an external documentation URL. For an agent to invoke it correctly, more context about the 'conta' object's fields and possible business rules is needed.
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%: both 'conta' and 'confirmar' have descriptions in the schema. The description adds no new parameter-level meaning beyond the endpoint context, so it merits the baseline score of 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 action ('Incluir Conta a Pagar') and the specific API endpoint (conta.pagar.incluir). This distinguishes it from related tools like olist_conta_pagar_obter or olist_contas_pagar_pesquisa by the 'incluir' verb, though it doesn't explicitly name alternatives.
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 this is for creating a new payable account, and explicitly notes that the operation alters data and requires confirm=true. However, it does not provide when-to-use/when-not-to-use guidance or contrast with sibling tools like olist_conta_pagar_baixar or olist_conta_receber_incluir.
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 says 'Pesquisar' (search) and provides an endpoint and documentation link, but it does not confirm read-only behavior, disclose return format, pagination, permissions, or potential side effects. The basic search intent is clear, but no substantial behavioral context is added.
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 and front-loaded: it states the purpose, the API endpoint, and a documentation link in two short sentences. Every part 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool being simple (one parameter, no output schema), the description omits crucial context such as what the search returns, any pagination behavior, and when to use it relative to similar tools. The documentation link may provide details, but the description itself is insufficient for an agent to fully understand the tool's behavior and output.
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 already provides 100% coverage for the single parameter idContrato with a clear description ('Id do contrato que será pesquisado'). The tool description does not add any additional parameter semantics beyond what the schema already states, so the 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 states a specific verb and resource: 'Pesquisar Adicionais de Contrato' (Search Contract Add-ons), which clearly distinguishes it from sibling tools like olist_contrato_adicional_incluir/excluir and olist_contratos_pesquisa. The API endpoint reference reinforces the exact operation.
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?
There is no explicit guidance on when to use this tool versus alternatives, no exclusions, and no mention of prerequisites. The name and verb imply a search operation, but the description does not state when this should be chosen over related tools like olist_contrato_obter or olist_contratos_pesquisa.
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?
Without annotations, the description carries the full burden of behavioral disclosure, but it only states the basic action and endpoint. It does not explicitly confirm this is a read-only operation, what the response contains, or any error/edge-case behavior. The provided documentation link is not accessible to the AI agent, so it adds no practical 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 concise, front-loaded with the purpose, and includes only the essential information: the action, the API version, and a documentation link. There is no redundant phrasing or unnecessary detail, making it efficient and easy to parse.
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 simple one-parameter get tool, the description is minimal but still incomplete. It does not explain what the returned data looks like (no output schema exists), when to use this tool vs. other CRM tools, or any behavioral caveats. The documentation link is not a substitute for inline context, leaving the agent with insufficient guidance for correct 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?
The input schema fully describes the single required parameter 'id' as 'Número de identificação do assunto do CRM na Olist', achieving 100% schema coverage. The description adds no further parameter details, so the 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 clearly identifies the action ('Obter' = get) and the resource ('Assunto do CRM'), distinguishing it from sibling tools like olist_crm_pesquisa (search) or olist_crm_incluir_assunto (create). It also specifies the API endpoint 'crm.obter.assunto', making the tool's function unambiguous.
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. It does not mention that this tool fetches a single subject by ID, nor does it contrast with search or create tools. The description lacks any context about prerequisites, typical use cases, 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?
With no annotations, the description carries the burden of disclosing behavior. It explicitly states that the operation alters data and requires confirmar=true, which is important mutation context. However, it does not explain side effects, reversibility, permissions, or error behavior, so transparency is only partial.
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 and front-loaded with the core purpose, followed by endpoint and documentation links. Every sentence adds useful information, though the URL is long and could be considered slightly heavy for a tool description.
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 simple 2-parameter schema and no output schema, the description provides adequate context: purpose, endpoint, documentation link, and a mutation warning. It is reasonably complete for an agent to invoke the tool safely, especially with the confirmar=true requirement clearly stated.
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%, and the schema already provides detailed meanings for idsExpedicao and confirmar. The description adds little beyond restating the confirmar=true requirement, so it neither improves nor harms parameter understanding.
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 a specific action ('Incluir agrupamento de expedições') and identifies the exact API endpoint, making the tool's purpose clear. It distinguishes itself from sibling expedition tools through the verb 'incluir' versus 'pesquisar', 'concluir', and 'obter', though it does not explicitly contrast them.
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 like olist_expedicao_pesquisar_agrupamentos or olist_expedicao_concluir_agrupamento. It warns that the operation mutates data and requires confirmar=true, but does not state prerequisites, exclusions, or typical use cases.
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 explicitly states 'Esta operação altera dados' (this operation changes data) and requires confirmar=true, which are critical to know. However, it does not disclose other behavioral traits such as side effects, reversibility, permissions, or response format.
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 sentences: purpose, endpoint/docs, and a warning about mutation and confirmation. It is front-loaded with the main verb and resource, though the long URL and endpoint string add some noise.
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 is adequate for a basic mutation tool: it names the operation, provides a documentation link, and warns about the mutation and confirmation requirement. However, it lacks information about return values (no output schema exists) and doesn't specify prerequisites or when to use this over sibling invoice tools, leaving gaps 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 input schema has 100% coverage for all three parameters, so the baseline is 3. The description adds minimal extra meaning beyond the schema, only reinforcing that confirmar must be true. It does not provide additional context about id or modelo beyond their schema descriptions.
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 generates an order invoice ('Gerar Nota Fiscal do Pedido'), with a specific verb and resource. It also includes the API endpoint and documentation link, but does not explicitly differentiate it from sibling tools like olist_nota_fiscal_emitir, which has a similar purpose.
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 alternatives. It mentions the operation alters data and requires confirmar=true, but that is a warning rather than usage context. No alternative tools are mentioned.
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 the operation 'altera dados' (mutates data) and requires confirmar=true, which is useful beyond the schema. However, with no annotations, it carries the full burden and does not explain what 'lançar estoque' does in practice, side effects, or whether it is reversible.
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 main purpose, then endpoint, documentation, and mutation warning. It contains no redundant fluff, though the structure could be slightly improved by separating the warning into its own sentence (it already is).
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?
For a simple tool with 2 parameters and no output schema, the description is minimally adequate, providing mutation semantics and confirmation requirement. However, it lacks information about return values, expected behavior, or prerequisites (e.g., the invoice must exist), which would be crucial for a mutation 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 semantic value beyond the schema: it repeats the confirmar=true requirement but does not explain the 'id' parameter beyond what is already 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 action ('Lançar Estoque da Nota Fiscal') and identifies the resource, but it does not differentiate this from sibling tools like olist_pedido_lancar_estoque or olist_nota_fiscal_lancar_contas. The endpoint name and doc link reinforce but do not add distinct purpose clarity.
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. It provides an endpoint and documentation link but does not state prerequisites, scenarios, or exclusions. The mutation warning is generic and not tied to use cases.
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 highlights that the operation mutates data ('altera dados') and requires 'confirmar=true', which is a key behavioral trait. Since no annotations are present, the description carries the burden, but it only adds this minimal disclosure; it doesn't detail consequences, permission requirements, or reversibility.
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 relatively short and front-loaded with 'Alterar Produto'. However, it includes an endpoint identifier and a documentation link that may not be immediately useful for an AI agent, slightly reducing efficiency.
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 tool has a nested 'produto' object with no defined properties in the schema, requiring external knowledge of the layout. The description provides a documentation link but does not explain how to identify which product to update or the expected data structure. Given the moderate complexity, the description is only partially 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?
The input schema covers both parameters (produto and confirmar) with descriptions, achieving 100% coverage. The tool description adds no extra parameter meaning beyond the already-present requirement for confirmar=true, so the baseline of 3 applies.
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 'Alterar Produto' (Change Product) and 'Esta operação altera dados', clearly indicating an update operation for a product. The verb 'alterar' and resource 'produto' are specific, and the name differentiates it from sibling alteration tools for other entities. However, it doesn't specify which product fields can be changed, so it's not fully specific.
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 only states the operation changes data and requires confirmation, without mentioning prerequisites, excluded cases, or comparison with related tools like olist_produto_incluir or olist_produto_obter.
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 the operation 'altera dados' (changes data) and requires 'confirmar=true', which is relevant since there are no annotations. However, this mostly repeats the schema's confirmar parameter description and does not mention side effects, reversibility, or return behavior. Given the absence of annotations, the description provides minimal but non-zero 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, containing three short sentences that provide the name, endpoint, documentation link, and a behavioral warning. It is front-loaded and avoids unnecessary details. Some redundancy exists with the tool name, but overall it is appropriately sized.
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?
The 'conta' object is completely unspecified ('conforme layout' with additionalProperties), and the description does not elaborate on required fields. No output schema is provided, and the description does not explain return values. The documentation link is helpful but shifts the burden to an external resource; for an agent, the description alone is insufficient.
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?
Both parameters have schema descriptions, so baseline is 3. The tool description adds no additional information about the 'conta' object structure or the confirmar flag beyond what the schema already states. The 'conta' parameter remains vague, but schema coverage is 100%.
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 operation is 'Incluir Conta a Receber' (include accounts receivable) and identifies the API endpoint. This distinguishes it from sibling operations like alterar, obter, and baixar. The verb 'incluir' makes 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 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 alternatives such as olist_conta_receber_alterar or olist_conta_receber_baixar. No prerequisites or exclusions are mentioned. The tool name implies a create operation but that is implicit, not explicit 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?
With no annotations, the description carries the full burden. It states the operation 'altera dados' and requires 'confirmar=true', which conveys that it is a mutating operation needing confirmation. However, it does not disclose whether it creates or updates (though the name suggests create), nor does it mention side effects, permissions, or response 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 concise and front-loaded with the tool's purpose. It includes a documentation link and explicitly mentions the mutability and confirmation requirement. No wasted words or redundant content.
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?
For a simple create-contact tool with two parameters, the description is moderately complete. It warns about the mutation and confirmar, but lacks details about the contact payload structure, expected return values, or additional context. The documentation link helps, but the description alone is insufficient for full operational 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?
Schema description coverage is 100%, so baseline is 3. The description reinforces the confirmar=true requirement but does not add extra meaning about the 'contato' object, which is under-specified in the schema (additionalProperties: {}). No additional parameter semantics are provided.
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 identifies the action as 'Incluir Contato' (include contact) and provides the API endpoint, making it obvious this is a contact creation operation. It is not purely tautological because it adds the endpoint and mutability note, but it does not explicitly elaborate on what a contact is or fully distinguish from the update tool.
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 olist_contato_alterar. The name and 'altera dados' imply a write operation, but there is no context for when to choose this over other contact-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?
Sem annotations, a descrição assume o encargo de revelar comportamento. Ela informa que a operação altera dados e exige confirmar=true, mas isso já está implícito no schema do parâmetro confirmar (const true). Faltam detalhes sobre efeitos colaterais, reversibilidade, permissões ou formato de retorno.
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 é curta e vai direto ao ponto, com o nome, endpoint e link. O texto é um pouco truncado ('Documentação: URL Esta operação...') sem pontuação entre o link e a próxima frase, mas o conteúdo é essencial.
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?
A ferramenta tem um objeto aninhado sem estrutura definida no schema e não possui output schema. A descrição deveria explicar o que é retornado ou quais são os pré-requisitos, mas apenas fornece um link externo. A informação é insuficiente para um agente operar corretamente sem consultar a documentação externa.
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?
O schema cobre 100% dos parâmetros com descrições. A descrição adiciona pouco além do endpoint e um link para o layout do objeto 'contrato'. O parâmetro 'contrato' é um objeto aberto com additionalProperties, e o link da documentação é útil, mas não detalha a estrutura.
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?
Descreve claramente 'Incluir Contrato' e especifica o endpoint API V2 'contrato.incluir', distinguindo-se de operações como 'olist_contrato_alterar' pelo nome. A frase 'Esta operação altera dados' confirma o caráter mutável, mas o objeto é inclusão. Há um link para documentação.
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 não fornece orientação sobre quando usar esta ferramenta versus alternativas como 'olist_contrato_alterar' ou 'olist_contratos_pesquisa'. A única orientação é a exigência de confirmar=true, que é uma condição de segurança, não um critério de seleçã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 must carry the behavioral transparency burden. It discloses that the operation changes data and requires confirmation, which is useful. However, it does not mention permissions, reversibility, response format, or potential side effects, so it is only partially transparent.
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 three short sentences. However, the first sentence ('Alterar Expedição API 2.0') largely repeats the tool name, making it slightly redundant. Still, the overall length is appropriate and information is front-loaded.
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?
This is a mutation tool with no annotations, no output schema, and a nested 'expedicao' object whose structure is vague ('conforme layout'). The description does not explain what fields are accepted, what the response looks like, or how to obtain the layout, leaving significant gaps for an agent to invoke it correctly. The provided documentation link is helpful but does not make the description self-contained.
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 already describes both parameters (confirmar and expedicao) with 100% coverage, so the description adds little beyond what the schema provides. The description's mention of 'confirmar=true' is redundant with the schema's 'const': true. No additional meaning is added about the 'expedicao' object's structure.
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 alters expedition data ('Alterar Expedição', 'Esta operação altera dados') and identifies the specific API endpoint. However, it does not specify what aspects of the expedition can be changed, so it is slightly vague on scope.
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 through its name and the phrase 'altera dados', and it gives a key requirement that 'confirmar=true' is needed to execute. It does not explicitly mention when to use this tool vs other expedition tools or provide any exclusions/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?
With no annotations, the description carries the burden of behavioral disclosure and states that the operation alters data and requires confirmar=true. This is useful, but it largely repeats schema constraints and does not mention side effects, permissions, or response 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 very concise, front-loaded with the operation name, and includes the endpoint and documentation link in a compact format. Every sentence provides useful information without unnecessary fluff.
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?
For a mutation tool with 6 parameters and no output schema, the description does not mention return values or provide usage alternatives. The 100% schema coverage and documentation link help, but the description is still minimal and leaves operational context to the external docs.
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 no additional parameter semantics beyond repeating confirmar=true, which is already 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 identifies a PDV-specific operation to include a note via XML, using the verb 'Incluir Nota via XML' and a specific endpoint. It distinguishes itself from generic siblings through the 'PDV' scope, but it doesn't explicitly state how it differs from olist_incluir_nota_xml.
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?
There is no explicit guidance on when to use this tool versus alternatives like olist_incluir_nota_xml or olist_nota_fiscal_incluir. The PDV scope implies a specific context, but no exclusions or alternative recommendations are provided.
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?
Without annotations, the description carries the burden of disclosing behavioral traits, but it only restates mutability and the confirmation flag, both already encoded in the schema's confirmar parameter (const true and 'operação mutável'). It adds no details on side effects, reversibility, permissions, or postconditions.
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 and front-loaded, containing the operation name, endpoint, documentation URL, and the key warning about mutation. It earns a 4 rather than 5 due to the awkward 'ReceberAPI' phrasing and the slight clutter of including API version and endpoint in the same sentence.
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 no annotations and no output schema, the description provides only the endpoint and the mutability requirement. It does not explain what 'baixar' means in terms of business outcomes, expected response, or the layout of the nested 'conta' object, making it minimally viable but with clear 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%, with 'conta' described as 'Dados da conta conforme layout' and 'confirmar' explicitly noted as required confirmation. The description adds no additional parameter semantics beyond what the schema already provides, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific operation 'Baixar Conta a Receber' and provides the exact API endpoint 'conta.receber.baixar', making the resource and action clear. It distinguishes from sibling tools like olist_conta_receber_incluir and olist_conta_pagar_baixar by name and endpoint, though it does not explicitly contrast them.
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 'Esta operação altera dados e exige confirmar=true', giving clear context that this is a mutating operation requiring confirmation. It does not mention alternatives or when not to use it, but this is sufficient guidance for a state-changing 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose that the operation modifies data and requires the confirmar flag, which is important. However, it does not describe specific side effects, prerequisites, or the nature of changes beyond the generic 'altera dados'. The schema's confirmar description already mentions 'mutable operation', so the description adds only marginal 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 concise and front-loaded. It states the purpose, provides the API endpoint and documentation link, and includes the critical behavioral note about data modification and confirmation. There is no fluff or redundant information; every sentence serves a purpose.
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?
The tool has a nested 'nota' object, no output schema, and no annotations. Given this complexity, the description is incomplete. It does not explain what a 'Nota Fiscal Consumidor' is, what the expected structure of 'nota' should be (beyond 'conforme layout'), what the return value is, or any potential side effects or error conditions. The documentation link provides external help, but the description itself leaves significant gaps for an agent to invoke the 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?
The schema has 100% description coverage, with both 'nota' and 'confirmar' having descriptions. The description text does not add any additional parameter semantics beyond what the schema already provides; it merely repeats the confirmar=true requirement. Since the schema adequately describes the parameters, the baseline of 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's function: 'Incluir Nota Fiscal Consumidor' (Include Consumer Invoice), with a specific verb and resource. It also names the API endpoint and provides a documentation link. However, it does not explicitly distinguish this tool from the sibling tool 'olist_nota_fiscal_incluir', which likely handles a different type of invoice.
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 some usage context: it states that the operation 'altera dados' (modifies data) and requires 'confirmar=true'. This implies that the tool is for submitting consumer invoices and that confirmation is needed, but it does not explicitly say when to use this tool versus alternatives like 'olist_nota_fiscal_incluir' or 'olist_incluir_nota_xml'. No explicit exclusions or alternatives are mentioned.
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, the description carries the safety burden and does state 'Esta operação altera dados e exige confirmar=true', warning the agent about mutation and confirmation requirement. However, it does not mention consequences, reversibility, auth needs, or response behavior, so transparency is only partial.
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 and front-loaded with purpose, followed by endpoint and docs link, ending with a mutation warning. Every sentence adds some context, though the endpoint string duplicates the tool name's semantics.
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 tool has a nested 'estoque' object with no concrete fields, no output schema, and no annotations, so the description should provide more operational scaffolding. It includes a documentation link and confirmation requirement, but without knowing the stock layout or return behavior, an agent may struggle to invoke it autonomously.
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 covers both parameters with descriptions, so the baseline is 3. The description adds no further parameter meaning beyond echoing 'confirmar=true'; the 'estoque' parameter's layout remains vague ('conforme layout'), so the agent must rely on external docs.
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 opens with 'Atualizar estoque do produto API 2.0', clearly identifying the action (update stock) and resource (product). This distinguishes it from sibling tools like olist_produto_obter_estoque and olist_produto_atualizar_precos, though it does not explicitly name alternatives.
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 gives no explicit when-to-use guidance or alternatives; it only states that the operation changes data and requires confirmar=true. The purpose statement implies usage for updating product stock, but there is no contrast with get-stock or other product mutation 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, the description discloses the mutation behavior ('altera dados') and the mandatory confirmation flag, which is useful safety context. However, it does not describe return behavior, side effects, or permissions, leaving the agent to consult the docs.
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 front-loads the core purpose, but it repeats the tool name and includes endpoint/version info that could be moved to metadata. Overall it is compact without unnecessary prose.
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?
For a mutation tool with a nested tag object and no output schema, the description is somewhat thin, but the documentation link compensates by pointing to full details. It does not cover return values or preconditions, so the agent may need external 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?
The schema fully describes both parameters (tag object and confirmar boolean with const true), so the description adds no new parameter details. The phrase 'exige confirmar=true' merely restates the schema constraint, and the 'tag' object layout is left to external documentation.
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 'Alterar Tag' and 'Esta operação altera dados', identifying it as a tag modification tool. The specific endpoint 'tag.alterar' distinguishes it from sibling search/inclusion tools, though it doesn't enumerate which tag fields can be changed.
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?
No explicit comparison to siblings like tag_pesquisa or tag_incluir is given, but the name and the confirmation requirement ('exige confirmar=true') imply it is for modifying existing tags with an explicit confirmation step. A documentation link is provided, yet no clear 'when vs alternatives' guidance is included.
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 disclose behavioral traits. It states that the operation alters data and requires confirmar=true, but this largely repeats the schema's confirmar description and does not explain the actual business effect, potential irreversibility, prerequisites, or side effects. The documentation link is helpful but does not substitute for inline 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 relatively short and front-loaded with the action 'Baixar Conta a Pagar'. It provides endpoint, documentation link, and safety warning without excessive verbosity. However, there is a small formatting issue ('Conta a PagarAPI') and some redundancy between 'API 2.0' and the endpoint.
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?
The tool has a nested 'conta' parameter with a vague schema description ('Dados da conta conforme layout') and no output schema. The description does not clarify the required layout, the exact effect of the operation, or the return value, relying on an external documentation URL. This leaves significant gaps for an agent attempting to use the 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%, with both parameters having descriptions. The description adds no extra parameter-level meaning; it only reinforces the schema's confirmar requirement. Baseline of 3 is appropriate since the schema handles parameter semantics 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 uses the specific verb 'Baixar' and resource 'Conta a Pagar', clearly indicating the operation of settling an accounts payable. It also provides the API endpoint 'conta.pagar.baixar', which distinctly differentiates it from the sibling tool 'olist_conta_receber_baixar' (accounts receivable).
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 'Esta operação altera dados e exige confirmar=true', giving clear context that this is a mutating operation requiring confirmation before execution. It does not mention alternatives or exclusions, but the context is sufficiently clear for an agent to understand when this tool is appropriate.
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 present, so the description correctly carries the safety burden by stating 'Esta operação altera dados e exige confirmar=true', disclosing that this is a mutating operation requiring explicit confirmation. It does not detail side effects on order/stock status, but the crucial mutation trait is clearly surfaced.
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: action, endpoint/documentation link, and mutation warning. It is concise, front-loaded, and every sentence contributes relevant information without redundancy.
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 a simple 3-parameter tool with no output schema, the description is minimally adequate: it covers purpose, mutation warning, and provides a documentation link. However, it omits return-value expectations, prerequisites, and conditional behavior (e.g., what happens when lancarEstoque='S'), leaving some gaps for the 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?
Schema description coverage is 100%, and all three parameters (id, confirmar, lancarEstoque) already have meaningful descriptions. The tool description adds no further parameter-level semantics beyond restating confirmar=true, so the baseline of 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 opens with 'Gerar Ordem de Produção do Pedido' and the API endpoint 'gerar.ordem.producao.pedido', clearly identifying the action (generate production order) and the resource (order). It is unambiguous but does not explicitly differentiate from sibling tools that also operate on orders.
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 instead of alternatives like olist_pedido_lancar_estoque or olist_gerar_nota_fiscal_pedido. The only usage-related statement, 'Esta operação altera dados e exige confirmar=true', is a constraint, not a selection guideline.
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 behavioral disclosure burden. However, it only states that the operation alters data and requires confirmation, both of which are already indicated by the schema's confirmar parameter. It does not disclose permissions, reversibility, side effects, or return behavior.
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 and front-loaded with the purpose, followed by endpoint, documentation link, and the key safety note. The endpoint line is slightly redundant with the tool name, but overall the description is concise and free of unnecessary filler.
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?
With no output schema and no annotations, the description should explain return values, prerequisites, or success/failure behavior, but it does not. The nested 'grupo' object is also under-specified, leaving the tool incomplete for reliable invocation despite the documentation link.
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%, but the 'grupo' parameter is an open object with only a vague 'Dados do grupo conforme layout' description. The documentation URL in the description is the only pointer to the actual layout, adding value beyond the schema. The confirmar parameter is already fully specified.
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 'Alterar Grupo de Tags' and states 'Esta operação altera dados', clearly identifying the tool as an update operation on tag groups. This distinguishes it from sibling tools like 'olist_grupo_tag_pesquisa' (search) and 'olist_grupo_tag_incluir' (include).
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 modifying a tag group and emphasizes that confirmar=true is required, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. The guidance is present but implicit.
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?
There are no annotations, so the description carries the burden of behavioral disclosure. It explicitly states 'Esta operação altera dados e exige confirmar=true', which warns that the operation is mutating and requires confirmation. However, it does not describe what happens after a successful call, error behavior, or reversibility, leaving some gaps for a write 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 brief and front-loaded with the core purpose ('Incluir Pedido'), followed by API details and a documentation link. It contains no filler or redundant information, and every sentence contributes useful context. This is a model of concise technical writing.
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?
For a tool with two parameters including a nested object and no output schema, the description is somewhat sparse. It provides the endpoint, a documentation link, and critical safety information, but does not mention what a successful response contains, any prerequisites beyond confirmation, or side effects beyond 'altera dados'. The documentation link partially compensates, but the description itself 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?
The input schema covers both parameters (pedido and confirmar) with descriptions, so baseline is 3. The tool description adds no extra parameter information beyond what the schema provides. The 'confirmar=true' requirement is already present in the schema's const, and the description merely repeats it. The pedido parameter description is vague ('conforme layout') and the tool description does not clarify 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 operation is 'Incluir Pedido' (include/create order) and identifies it as an API V2 endpoint 'pedido.incluir'. It explicitly notes that the operation alters data, distinguishing it from read-only operations. The inclusion of a documentation link provides additional context, making the purpose unambiguous relative to sibling tools like olist_pedido_alterar.
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 such as olist_pedido_alterar or olist_pedido_obter. It explains that the operation modifies data and requires confirmar=true, but does not mention specific use cases, prerequisites, or exclusions. Users must infer from the tool name and context that it is for creating new orders.
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 disclosure burden. It discloses that the operation mutates data and requires confirmar=true, which is important for safe invocation. However, it does not mention permissions, side effects, or response behavior, so it is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences front-loaded with the purpose. It efficiently includes the endpoint, documentation link, and the critical confirmation requirement without unnecessary 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 simple 3-parameter mutation with no output schema, the description provides sufficient context: it names the operation, notes the API version and docs, and flags the confirmation flag. It lacks only explicit details about return format, which is not present in the schema but may be inferred from the operation type.
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 each parameter already documented in the input schema. The description adds no additional parameter semantics beyond repeating that confirmar=true, so it meets the baseline without adding 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's function: 'Alterar estágio do assunto do CRM API 2.0' (change the stage of a CRM subject). It identifies the specific verb and resource and references the API endpoint, making it distinct from sibling CRM tools that handle other actions.
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 'when to use' guidance or alternatives. It does not reference sibling tools like olist_crm_lista_estagios_assunto or olist_crm_alterar_situacao_acao, leaving the agent to infer usage from the name alone.
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 present, so the description must carry the full burden. It states that the tool retrieves account information, implying a non-mutating operation, but it does not disclose any additional behavioral traits such as authentication requirements, potential side effects, or response specifics. The description repeats the tool's purpose without adding behavioral context beyond it.
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 short sentences including the endpoint and documentation link. It wastes no words and is 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?
For a zero-parameter info tool, the description is adequate: it states what it does, identifies the endpoint, and provides a documentation link. However, it does not mention what type of information is returned or any auth context, which could be relevant for a no-annotations 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, and the input schema's properties are empty (100% schema coverage). The description appropriately focuses on the operation itself; parameter details are not needed. Baseline 4 for zero-parameter tools applies.
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: 'Obter informações da conta API 2.0' (Get API account information). The verb 'obter' with resource 'informações da conta' is specific, and it distinguishes from sibling tools that target specific entities (contacts, products, orders, etc.).
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. It only states the endpoint and documentation link, without explaining scenarios or prerequisites. Since there are many sibling tools, explicit context or exclusions would be helpful.
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 present, so the description must carry the transparency burden. It does disclose that this is a mutating operation and requires confirmation, which is key behavioral context. It does not detail other side effects like email delivery or status changes, but the schema's 'enviarEmail' param covers some of that.
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?
Three short sentences, front-loaded with purpose, endpoint, and mutation warning. The first two sentences are slightly redundant ('API 2.0' appears twice), but overall efficient. Documentation link adds value.
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?
For a simple 3-parameter tool, the description covers purpose, mutation, and confirmation requirement. However, it lacks what happens after sending (return value or status change) and doesn't relate to sibling tools or prerequisites. Documentation link mitigates but isn't inline.
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 parameters are well-documented. The description adds no extra semantic beyond re-stating that 'confirmar' must be true, which is already captured by the schema's 'const': true. Thus, 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 opens with 'Enviar uma NFS-e API 2.0', giving a clear verb and resource. It also specifies the endpoint 'nota.servico.enviar'. However, it doesn't explicitly contrast with sibling tools like 'incluir' or 'consultar', so the agent might not know exactly when to prefer 'enviar'.
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?
It warns that 'Esta operação altera dados e exige confirmar=true', which implies use requires confirmation, but it doesn't provide explicit when/when-not guidance or alternatives. The documentation link is provided but not inline 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, the description carries the burden of behavioral disclosure. It explicitly states 'Esta operação altera dados' (this operation changes data) and 'exige confirmar=true' (requires confirm=true), which is valuable context about mutation and the confirmation requirement. However, it does not mention error handling, idempotency, or response behavior.
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 two sentences total. It front-loads the purpose, then adds the endpoint and a mutation warning. The documentation URL is slightly redundant but does not detract significantly.
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?
While the description covers the core purpose and mutation safety, it lacks context about expected return values (no output schema exists), possible errors, or when to use this operation relative to other separation-related tools. The absence of output schema means the description should explain the response, but it does not.
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 already provides descriptions for all three parameters, covering 100% of them. The description only reinforces the confirmar=true requirement, which is already present in the schema as a const. No additional parameter semantics are added 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 identifies the tool's purpose: 'Alterar Situação de uma Separação' (change the status of a separation). It also specifies the API endpoint and provides a documentation link, making it distinct from sibling tools like olist_separacao_pesquisa and olist_separacao_obter.
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 alternatives, nor does it mention exclusions or prerequisites. It only states the operation mutates data and requires confirmar=true, but no contextual workflow or decision-making information.
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, the description carries the burden of behavioral disclosure. It explicitly states the operation alters data and requires confirmation, which is a key safety trait. However, it does not describe side effects, reversibility, or required permissions, leaving some transparency 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, leading with the purpose and then providing the endpoint, documentation link, and mutation warning. Every sentence contributes useful information, though the endpoint is somewhat redundant with the name.
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 mutation tool with only two scalar parameters and no output schema, the description is quite complete. It covers what the operation does, its mutating nature, the confirmation requirement, and provides a documentation link for further detail. Minor omissions like specific business impact are not critical given the simplicity.
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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds no new semantic detail about the parameters themselves, only mentioning confirmar=true in the mutation warning, which is already 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's function with a specific verb and resource ('Concluir agrupamento de expedições'), which distinguishes it from siblings like 'incluir_agrupamento' and 'pesquisar_agrupamentos'. The endpoint name further clarifies the exact operation.
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 clear context that this operation mutates data and requires confirmar=true, implying it should be used when concluding a grouping with confirmation. However, it does not explicitly mention when to use this tool instead of alternatives or provide any 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 explicitly warns that the operation 'altera dados e exige confirmar=true', which discloses the mutating nature and confirmation requirement. However, with no annotations provided, the description carries the full burden, and it does not disclose other behaviors like response format, error cases, or side effects beyond mutation. The docs link is a pointer but not embedded information.
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, front-loading the purpose and then giving endpoint, docs, and a necessary warning. Every sentence adds value, so it earns a 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?
Given no output schema and no annotations, the description is moderately complete but lacks return-value information and explicit guidance on when this tool should be chosen over similar siblings. The docs link partially compensates, but the description alone leaves 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?
The schema covers 100% of parameters with clear descriptions, so the description doesn't need to add parameter details. It does not add anything beyond the schema, so baseline 3 applies.
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 includes an invoice via XML ('Incluir Nota via XML API 2.0'), and the endpoint and documentation link reinforce the action. The 'via XML' differentiates it from sibling tools like olist_nota_fiscal_incluir, making the purpose specific and distinguishable.
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 when an XML invoice needs to be included, but does not explicitly state when to use this tool versus alternatives such as olist_nota_fiscal_incluir or olist_pdv_incluir_nota_xml. The only guideline is the warning that confirmar=true is required, which is more of a prerequisite than a usage context. This warrants a 3.
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, the description carries the burden. It does explicitly disclose that the operation alters data and requires confirmation. However, it repeats the confirmar parameter's schema information and does not add deeper context about side effects, permissions, or reversibility. The endpoint and documentation link are useful but not behavioral disclosures.
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, front-loaded with the purpose, and every sentence contributes: name/version, endpoint, documentation link, and safety warning. No fluff or redundancy beyond the brief mutation statement.
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?
This is a simple create operation with two required parameters (one nested object) and no output schema. The description provides the endpoint and a documentation link, covering some gaps. However, it does not describe what the response looks like, nor does it explain the 'layout' of the nota object, which is critical for correct invocation. It is minimally viable but lacks depth.
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 adds no extra meaning beyond the schema; it only restates the confirmar requirement. The 'nota' parameter remains vaguely defined as 'Dados da nota conforme layout', matching the schema. No additional parameter semantics are provided.
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 'Incluir Nota de Serviço' (include service note), a specific verb+resource. It distinguishes from sibling tools like 'obter', 'enviar', and 'consultar' by using the 'incluir' verb. The endpoint reference adds further specificity.
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 implied usage context via the name and the mutation warning, but it does not explicitly state when to use this tool versus alternatives. It mentions the operation alters data and requires confirmar=true, which is a precondition rather than a usage guideline. No explicit alternatives or exclusions are 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 must carry the burden. It explicitly states 'Esta operação altera dados' (this operation changes data) and requires 'confirmar=true', which is key mutability information. However, it lacks details on side effects, reversibility, prerequisites, or what happens on success, and the schema's confirmar description already implies mutability. The endpoint and doc link add some operational 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 extremely concise: two sentences and a documentation URL. It front-loads the main purpose, then specifies the endpoint and key behavioral requirement. There is no redundant fluff, though the tool name and endpoint overlap slightly. Every sentence provides useful information.
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 mutating operation with a nested object parameter that accepts arbitrary properties, the description lacks critical context. It does not explain what the 'adicional' layout should contain, what the response looks like, or any prerequisites. The documentation URL is helpful but not self-contained, and there is no output schema to compensate. The agent is left without enough guidance to construct a valid request.
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%, both parameters have descriptions. The 'confirmar' parameter is well-documented with const=true and explains mutable operation confirmation. The 'adicional' parameter description is vague ('Dados do adicional conforme layout') and the tool description adds no further detail, so the heavy lifting remains on the schema. Baseline of 3 applies due to high coverage.
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 operation: 'Incluir Adicional de Contrato' (Include Contract Additional), with the specific endpoint 'contrato.adicional.incluir'. This is a specific verb+resource that distinguishes it from sibling tools like 'pesquisa' (search), 'excluir' (delete), and 'alterar' (update). The API version is also noted.
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 that this is a mutating operation requiring 'confirmar=true', guiding when to use it. It does not explicitly list alternatives or exclusions, but the tool name and sibling list make the use case evident (adding an additional to a contract versus searching or deleting).
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 of behavioral disclosure. It only states the endpoint and action, omitting details about whether the operation is read-only, what the response contains, or any authentication or rate-limit considerations. The documentation link offers external details but the description itself is thin.
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 the purpose front-loaded and no redundant words. It includes the API version, endpoint identifier, and a documentation link, all of which are informative and earn their 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?
For a simple, parameterless retrieval tool, the description provides adequate context: it names the resource, API version, and endpoint, and gives a docs link. The term 'Árvore de Categorias' implies a hierarchical return structure, so the lack of an explicit output description is acceptable.
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 an empty schema, so there is nothing to document. Per the rubric, a baseline of 4 is appropriate because the description adds no parameter information but also does not need to; the schema fully covers the (nonexistent) 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 obtains the product categories tree ('Obter Árvore de Categorias dos Produtos'), which is a specific verb+resource. This distinguishes it from sibling product tools like olist_produtos_pesquisa and olist_produto_obter.
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 retrieving product category hierarchies, but it does not explicitly state when to use it or mention alternatives. No exclusions or alternative tool references are provided, leaving the guidance implicit rather than explicit.
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 burden of behavioral disclosure. It explicitly warns 'Esta operação altera dados' (this operation changes data) and 'exige confirmar=true', informing the agent that this is a mutating operation requiring explicit confirmation. It does not detail side effects or permissions, but the key behavioral trait is disclosed.
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 front-loaded with the core action 'Excluir Adicional de Contrato'. It includes an endpoint and documentation URL, which add some redundancy but are not excessive. The final sentence about mutation and confirmar=true is valuable. Overall, it is concise with minimal waste.
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 delete operation with two well-described parameters and no output schema, the description covers the essential aspects: what it does, that it mutates data, and the confirmation requirement. It also provides a documentation link for deeper details. Lack of error/response information is acceptable given the tool's simplicity.
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 already covers both parameters with descriptions (id and confirmar), achieving 100% schema description coverage. The description's 'exige confirmar=true' simply restates the schema's const: true constraint, adding no new semantic information. 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 operation: 'Excluir Adicional de Contrato' (delete contract add-on), naming both the action and resource. It also provides the exact API endpoint and documentation link. This distinguishes it from the sibling tool olist_contrato_adicional_incluir.
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?
Usage is implied by the verb 'Excluir' and the resource name, but the description does not explicitly state when to use this tool versus alternatives. It does mention the operation mutates data and requires confirmar=true, which is useful conditional guidance, but lacks comparisons to other contract 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?
With no annotations, the description carries full burden. It explicitly states 'Esta operação altera dados e exige confirmar=true', transparently disclosing that it is a mutating operation requiring confirmation. This is valuable context beyond the name, though it does not detail other side effects or permissions.
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 sentences plus a link, with the purpose, endpoint, and a critical safety caution front-loaded. Every word earns its place; no filler or redundant repetition of schema details.
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?
For a 7-param mutation tool with no output schema or annotations, the description is thin. It provides the endpoint, mutation warning, and doc link, but lacks usage guidance and context on optional parameters. However, the schema fully describes parameters, so completeness is moderate.
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 3 applies. The description adds minimal parameter information beyond the confirmar=true requirement, which aligns with the schema's const. It does not clarify the estornarContas/estornarEstoque parâmetros, relying entirely on 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 states 'Cancelar Nota via XML' (cancel invoice via XML), a specific verb+resource, and identifies the PDV scope and API endpoint. This clearly distinguishes it from sibling tools like olist_pdv_incluir_nota_xml (include) and olist_nota_fiscal_obter (retrieve).
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 use for cancelling PDV invoices via XML but does not explicitly state when to use this tool versus alternatives. It provides an endpoint and documentation link but lacks exclusions or comparisons with other cancel/note 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Esta operação altera dados e exige confirmar=true', alerting the agent that this is a mutating operation requiring confirmation. It also provides a documentation link. However, it does not detail side effects or specific data affected beyond the general statement.
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, front-loaded with the purpose and including the endpoint and documentation. Every sentence provides useful information without redundancy or padding.
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 simple params, no output schema) and the lack of annotations, the description covers the essential context: what the operation does, the API endpoint, documentation, and the mutating nature requiring confirmation. It does not describe return values or error behavior, but that is not critical for this mutation-focused 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 schema already describes both parameters (id and confirmar) with 100% coverage. The description adds no additional parameter semantics beyond reiterating that confirmar must be true, which is already encoded in the schema as a const.
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 operation: 'Estornar Estoque do Pedido' (reverse order stock) with a specific verb and resource. It also provides the exact API endpoint (pedido.estornar.estoque) and notes it's API 2.0, distinguishing it from sibling tools like olist_pedido_lancar_estoque.
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 the tool (to reverse order stock) but does not explicitly state alternatives or exclusions. It mentions the confirmation requirement and gives a documentation link, but lacks clear guidance such as 'use this instead of X' or 'do not use if...'.
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 explicitly discloses that the operation mutates data ('altera dados') and requires a confirmation flag. This is essential behavioral information, though it does not mention reversibility, return values, or failure modes.
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 and front-loaded with the main purpose. It contains some redundancy ('API 2.0' vs 'API V2') but no wasted sentences, and the documentation link is useful.
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 tool with one parameter and no output schema, the description covers purpose, endpoint, documentation, mutation risk, and the confirmation requirement. It does not explain how price values are supplied, but the schema and docs partially compensate.
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%; the only parameter (confirmar) is already described fully in the schema. The description reinforces that confirm=true is required but adds no new parameter-level 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 description clearly states the action ('Atualizar preços') and the resource ('produto'), identifying a specific price-update operation. This distinguishes it from sibling tools such as olist_produto_alterar (general product update) and olist_produto_atualizar_estoque (stock update).
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 useful context: it names the API V2 endpoint, includes documentation, and states the operation requires confirm=true. It does not explicitly contrast with alternative price-related tools like listas_precos, so it stops short of full when/when-not guidance.
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:

[![olist-mcp MCP server](https://glama.ai/mcp/servers/mauriciogior/olist-mcp/badges/card.svg)](https://glama.ai/mcp/servers/mauriciogior/olist-mcp)

Score Badge

Copy to your README.md:

[![olist-mcp MCP server](https://glama.ai/mcp/servers/mauriciogior/olist-mcp/badges/score.svg)](https://glama.ai/mcp/servers/mauriciogior/olist-mcp)

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/mauriciogior/olist-mcp'

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