Conta Azul MCP

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

The description discloses the tool's behavior: it returns a login URL when called with no args, and sets the token when called with a token. The idempotentHint annotation is consistent, suggesting repeated calls with the same token are safe. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences covering all necessary information. It is front-loaded with context about the intended audience and workflow, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides sufficient context for an authentication tool, covering the core workflow and parameter usage. However, it lacks details about error handling or the exact format of the return value (though the 'link' is implied). The presence of annotations partially compensates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage for the single optional parameter. The description adds significant value by explaining when to omit the parameter (to get the link) and when to include it (to authenticate), making the semantics crystal clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs and resources: 'log in', 'copy access token', 'paste', and 'call with token' clearly defines the tool's function. It distinguishes from siblings by explicitly targeting IDE agents and detailing the authentication workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states when to use with or without the token argument, providing a two-step usage pattern. While it does not explicitly mention alternative tools like 'connect', the context is clear enough for appropriate invocation.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so safety is clear. The description adds context about conditional return states (all connected vs missing credentials), which is valuable beyond the annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. Front-loaded with the main purpose, then specific state details. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, the description provides complete context: it explains what is returned in different states (all connected vs missing credentials) and mentions the key fields (authenticated, pending, connect_url). Adequate for a simple read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so schema coverage is 100%. The description naturally adds no parameter info, but per calibration for 0 params, baseline is 4. The description is sufficient given no parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns connection status and URLs, with a specific verb 'returns' and resource 'connection status'. It distinguishes from siblings like 'authenticate' by focusing on status check rather than performing authentication.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking connection status but does not explicitly state when to use this tool vs alternatives like 'authenticate' or 'toolkit_info'. No exclusions or when-not guidance are provided.

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

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

Annotations already provide destructiveHint=true. The description adds that it 'cancela/remove' a contract and supports batch execution, which aligns with the destructive hint. However, no additional behavioral traits (e.g., side effects, irreversibility) are disclosed beyond what annotations imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two concise, front-loaded sentences. Every word contributes: the action and bulk support are immediately clear. No extraneous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is destructive with three parameters and no output schema, the description covers the basic action and bulk capability. However, it lacks details on return values, prerequisites, or potential side effects, which are important for a destructive operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, but the description only reiterates bulk support for the 'ids' parameter. The 'account' parameter is already described in the schema. No additional meaning is added for 'id' (undocumented). The description adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool cancels/removes a contract, which is a specific verb+resource. It distinguishes from sibling tools like contaazul_contract_write (create/update) and contaazul_get_contract (read). The mention of bulk support 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies bulk usage but does not provide explicit when-to-use or when-not-to-use guidance. No mention of prerequisites or alternatives, leaving the agent to infer 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.

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

Annotations only indicate non-read-only and non-destructive, but the description does not disclose behavioral traits such as required permissions, effects on other entities, rate limits, or failure modes. For a write operation, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two short sentences. No redundant or unnecessary information is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and minimal annotations, the description fails to provide sufficient context for correct usage. It omits return value, error handling, and structure of the JSON payload, making it incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (only 'account' described). The description adds meaning to 'data' by noting it is a JSON payload, but does not explain expected fields or format. 'account' is covered by schema, so net value is moderate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Cria um contrato' (creates a contract), providing a specific verb and resource. However, it does not differentiate from sibling tools like contaazul_contract_cancel or contaazul_get_contract, leaving some ambiguity about scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like contaazul_sale_write_create or contaazul_person_write_create. There is no mention of prerequisites, when not to use, or contextual indicators.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds value by specifying the returned fields, but it does not disclose any additional behavioral traits beyond those implied by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is one concise sentence in Portuguese, front-loading the key purpose. No wasted words, though it could be slightly expanded for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description is mostly adequate. It fails to mention usage context or edge cases (e.g., multiple accounts), but the schema parameter description compensates partially.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter, so baseline is 3. The tool description does not add any extra meaning about the parameter; the schema already explains how to identify the account.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves company data (CNPJ, corporate name, tax regime) from Conta Azul. It effectively distinguishes from sibling tools like contazul_get_person by specifying it's for the active company.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like contazul_list_accounts or other getters. It does not mention prerequisites or when it should not be used.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is clear. The description adds the bulk execution capability, but does not disclose other behavioral traits such as error handling or response structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences: one stating the core purpose and one highlighting a key feature (bulk support). No extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential purpose and bulk capability, but lacks details about return values, error handling, or clarification of the 'account' parameter's context. Given the absent output schema and many sibling tools, more completeness would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67%, with 'ids' and 'account' having descriptions in the schema. The tool description reinforces that 'id' is the contract ID, but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves contract details by ID ('Detalhe de contrato por id'). It distinguishes itself from sibling tools like 'contaazul_list_contracts' which lists contracts, and from write tools like 'contaazul_contract_write'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The bulk support hint is present, but there is no mention of when not to use it or comparison to similar tools like 'contaazul_list_contracts'.

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

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

The description adds the behavioral trait of bulk support via 'ids', which is not fully covered by annotations (readOnlyHint, idempotentHint, destructiveHint). However, it does not disclose other behaviors like authentication needs or rate limits. The safety profile is already clear from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the main purpose and followed by bulk mode clarification. No superfluous text; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no output schema, few parameters), the description provides the essential information but omits details like return structure, error scenarios, or when to use the 'account' parameter. It is minimally adequate for a safe, read-only tool with good annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% (id parameter lacks description). The description does not add meaning beyond the schema: it mentions 'por id' but does not clarify the 'id' parameter's format or constraints. The 'account' parameter's purpose is explained only in the schema, not reinforced. No added semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Detalhe de uma parcela por id' (detail of an installment by id), indicating retrieval. It also mentions bulk support. However, it does not differentiate from the sibling tool 'contaazul_list_installments' (which lists installments) or other get tools, leaving slight ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. Usage is implied: when you have an installment id and need details. No exclusions or alternatives are mentioned, such as preferring 'contaazul_list_installments' for filtering or 'contaazul_settle_installment' for modifications.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's main addition is the bulk execution capability ('accepts ids for batched execution'). No further behavioral details like rate limits or authentication are provided, but annotations cover the safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with purpose. No unnecessary words. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a retrieval tool with no output schema, the description omits what details are returned. Given the complexity of the domain and sibling tools, mentioning return fields would improve completeness. The bulk support is noted, but the full context is slightly lacking.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67% (2 of 3 parameters have descriptions). The overall description reinforces the 'ids' parameter with 'Bulk support' but adds no new semantic meaning beyond the schema. The 'id' parameter lacks description, and 'account' is explained in its schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Detalhe de uma NF-e por id' (detail of an NF-e by id) and mentions bulk support. The name 'get_invoice_nfe' aligns with the purpose and distinguishes from sibling list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives like 'contaazul_list_invoices_nfe' or other get tools. No when-not or exclusion criteria are given.

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

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

Annotations already declare readOnlyHint true, idempotentHint true, destructiveHint false. Description adds bulk execution behavior but does not disclose error handling, auth requirements, or rate limits. Some value added beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded sentences with no superfluous text. Every word adds value: purpose and bulk support.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get-by-ID tool, the description is adequate with annotations and schema. A hint about the return structure (e.g., 'returns person details') would improve completeness, but current wording implies it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are sufficiently described in the schema. Description adds no extra meaning beyond stating the tool gets person details and supports bulk via 'ids'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states 'Detalhe de uma pessoa por id' (detail of a person by ID), clearly specifying the verb (get) and resource (person). The 'Bulk support' note further clarifies capability, distinguishing from sibling list_people.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies use when a person ID is known, but does not explicitly state when to use vs alternatives like contaazul_list_people. No when-not-to-use or exclusion criteria are provided.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. The description adds that it supports batched execution via the 'ids' parameter, which is a useful behavioral detail beyond annotations. However, it does not mention error handling or return value structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with only two sentences. The main purpose and bulk support are front-loaded. Every word serves a purpose; no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get operation, the description provides the core purpose and bulk capability. However, it lacks details about the return format, error handling, or what 'detalhe' includes. No output schema exists, so more completeness would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67% (2 of 3 parameters described). The tool description repeats the bulk mode for 'ids' but does not add new meaning beyond the schema. For 'account', the description in the tool is absent; it only appears in schema. Thus, description adds limited semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Detalhe de produto por id' (Product detail by id), specifying the action (get detail) and resource (product by ID). It also mentions bulk support, distinguishing it from list tools and other get tools for different entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when needing product details by ID, but does not explicitly state when to use this tool versus alternatives like contaazul_list_products for listing all products. No when-not-to-use 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description's claim of retrieving details aligns. It adds value by mentioning bulk support via ids, providing behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the main purpose. Every word earns its place; no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get-detail tool with no output schema, the description omits return value information. It is adequate for basic use but lacks completeness in explaining what the tool returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage of parameters is 67% (descriptions for ids and account, not id). The description adds minimal extra meaning—only 'bulk support' is mentioned, which is already in the ids parameter description. No new syntax or format details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Detalhe de uma venda por id' (detail of a sale by id), clearly indicating the verb (get detail) and resource (sale). The mention of bulk support adds scope, and it distinguishes from list siblings like 'contaazul_list_sales'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for fetching a specific sale, but does not explicitly state when to use this tool vs alternatives (e.g., 'contaazul_list_sales' for listing). No exclusions or when-not guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no new behavioral context beyond the output fields. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the main action and output details. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with one optional parameter and no output schema, the description adequately explains what it does and what it returns. It could be more explicit about the return format and the meaning of 'install', but overall it is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the parameter description. The tool description adds minimal value by suggesting the parameter is used for filtering when multiple companies exist, but it is self-referential ('Ver contaazul_list_accounts'). For complete schema coverage, baseline is 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool lists Conta Azul companies linked to the install, specifying the returned fields (company_id, label). This is a specific verb+resource combination that distinguishes it from sibling list tools that list other entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used to retrieve linked companies, but it does not explicitly state when to use it versus alternatives like authenticated tool or other listing tools. No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which inform the agent of safe read behavior. The description adds no additional behavioral context (e.g., pagination, sorting, authentication requirements).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise and front-loaded. However, it is so short that it borders on under-specification, lacking details that could be added without sacrificing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given four parameters, no output schema, and only 50% parameter documentation, the description is incomplete. It does not explain what DRE means, how pagination works, or provide expected response structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no information about the four parameters. Schema coverage is only 50% (only 'tipo' and 'account' have descriptions). The description does not compensate for the undocumented 'pagina' and 'tamanho_pagina' parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Lista categorias financeiras (DRE)' which clearly indicates the tool lists financial categories (DRE). It distinguishes from sibling list tools by specifying the entity type (categories vs. accounts, contracts, etc.), though it does not explicitly differentiate itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when or when not to use this tool versus alternatives. The description lacks context about typical use cases, preconditions, or recommended scenarios.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already convey safety and idempotency. The description adds that it lists contracts with filters and bulk execution, consistent with annotations but not adding significant behavioral context like rate limits or auth needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (two sentences) and front-loaded with the main action. It could be more structured, but it efficiently conveys core functionality for a simple list operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters and no output schema, the description is incomplete. It does not explain pagination behavior, default sort order, maximum results, or how bulk mode interacts with other filters. The agent lacks sufficient context to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33% (two parameters have descriptions). The description merely lists parameter names without explaining their meanings or constraints beyond what the schema already provides. It does not compensate for the low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Lista contratos' (lists contracts) and lists filter parameters, clearly indicating it's a list tool. It differentiates from sibling single-record tools like contaazul_get_contract by implication, but does not explicitly compare.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions filters and bulk support (cliente_ids), giving some guidance on usage. However, it lacks explicit when-to-use vs alternatives, such as recommending this tool for listing contracts instead of other list tools or single-record lookups.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds no behavioral details beyond that. Since annotations cover the key traits, the description is not harmful but adds no value. There is no contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise (four words) but under-specified. Important details are missing. Front-loading is trivial, and the description does not earn its place because it provides no actionable information beyond the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema. The description omits pagination, filtering, ordering, or any return format details. For a listing tool, this is insufficient. The complexity is low, but the description still fails to provide complete context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only 33% of parameters have schema descriptions. The tool description does not mention or explain any parameters. It adds no meaning beyond what is in the input schema. Given the low coverage, the description should compensate but fails to do so.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Lista centros de custo' clearly states the tool lists cost centers. It uses a specific verb (list) and resource (cost centers), so purpose is clear. However, it does not differentiate from sibling list tools like 'contaazul_list_accounts' or others, and the minimal phrasing lacks distinguishing context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description does not mention conditions, prerequisites, or exclusions. With many sibling list tools, the absence of usage context is a significant gap.

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

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

Annotations already declare the tool as read-only and idempotent. The description adds minimal behavioral context beyond listing account types, missing details on pagination limits or authentication.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the core purpose. Every word is essential, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with pagination, the description covers the essential purpose. Minor gaps exist: no mention of return format or default pagination, but the complexity is low.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is low (33%), and the description adds no parameter meaning beyond the schema's existing descriptions. For pagination parameters (pagina, tamanho_pagina), no additional context is given.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Lista contas financeiras (banco, caixa, cartão)' clearly states the tool lists financial accounts of specific types, differentiating it from sibling list tools like contaazul_list_accounts which likely handles company accounts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives; the name and description imply it's for financial accounts, but no direct exclusions or context for selection are provided.

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

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

Annotations already declare `readOnlyHint: true`, `idempotentHint: true`, and `destructiveHint: false`, making the tool's non-destructive nature clear. The description adds that it lists financial events with filters but does not disclose additional behavioral traits like pagination handling or response structure. The bar is lowered due to annotations, so a score of 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a single sentence and a list of filters. It is front-loaded with the core action and effectively communicates the purpose without extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 7 parameters and no output schema, yet the description does not mention return values (e.g., structure of installment objects) or pagination behavior. It also misses listing the `account` parameter. This leaves significant gaps for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 14% (only `account` has a description). The description lists parameter names but lacks details on formats (e.g., date strings in `data_vencimento_inicio`), allowed values for `tipo` and `status`, and usage constraints. With low coverage, the description should compensate but does not add meaningful semantics beyond the parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists installments (financial events), which is a specific verb-resource pair. It distinguishes itself from sibling tools like `contaazul_get_installment` (single) and other list tools by focusing on installments.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists available filters (page size, page, date range, type, status), implying when to use this tool for filtered queries. However, it does not explicitly state when not to use it or provide alternatives, such as using `contaazul_get_installment` for a single installment.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds filter names but no additional behavioral context such as pagination behavior, rate limits, or response details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence that front-loads the purpose and lists filters concisely. It could be improved with structured formatting (e.g., bulleted filters) but is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 parameters, no output schema, and low schema coverage, the description is insufficient. It does not explain pagination, return format, allowed status values, or how date filters work. More context is needed for a list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 17%, so the description should compensate. It lists filter parameter names (pagina, tamanho_pagina, etc.) but does not explain their meaning, format, or constraints. For non-Portuguese speakers, terms like 'data_emissao_inicio' are not self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists issued invoices (NF-e) and lists the available filters. This distinguishes it from sibling tools like contaazul_get_invoice_nfe (single retrieval) and other list tools for different entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing NF-e invoices via filters, but does not explicitly state when to use this tool versus alternatives such as get_invoice_nfe for a single invoice or other list tools. No guidance on prerequisites or when not to use is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that bulk support exists via fornecedor_ids, but does not elaborate on side effects, rate limits, or data freshness. The added value over annotations is modest.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences with no unnecessary words. The key purpose and filter list are front-loaded. Every sentence adds value, and there is no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 8 parameters and no output schema, the description does not explain return values, pagination behavior, or default values. Important context like date format for data_inicio/data_fim is missing. The description feels incomplete for a fairly complex query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25%, and the description merely lists parameter names like 'tamanho_pagina', 'pagina', 'data_inicio', etc., without explaining their meaning, format, or usage. The description does not compensate enough for the low schema coverage, leaving many parameters unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Lista contas a pagar' (list accounts payable) in Portuguese, distinct from sibling tool 'contaazul_list_receivables' which lists receivables. The verb 'listar' and resource 'contas a pagar' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists available filters, implying the tool is used to query payables with those filters. However, it does not explicitly state when to use this tool over siblings or when not to use it. The sibling names provide context, but no direct guidance is given.

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

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

Annotations indicate readOnlyHint=true, destructiveHint=false. Description adds behavioral context about filtering and pagination capabilities, which is consistent and adds value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is two sentences, front-loaded with purpose, and contains no redundant information. Every part serves a clear function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and 6 parameters, the description lacks return structure details (e.g., fields returned) and pagination behavior beyond basic filter listing. For a list tool, this is somewhat incomplete, though basic usage is covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (33%). Description lists parameter names and notes 'busca' is for name/document, but provides no additional detail on 'pagina' or 'tamanho_pagina' beyond schema constraints. The 'account' parameter is only described in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool lists people (clientes, fornecedores, vendedores, transportadores). The verb 'Lista' and resource 'pessoas' are specific, and it distinguishes from siblings like 'contaazul_get_person' and other list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description lists filter parameters (tamanho_pagina, pagina, busca, tipo, ativo) providing usage context. However, it does not explicitly state when to use this tool instead of alternatives like 'contaazul_get_person' for individual lookups.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds the list of filter parameters, which is consistent but does not disclose additional behavioral traits like pagination limits or order of results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short, consisting of one sentence and a list of filters. No wasted words, but it could be slightly more structured with brief explanations of each filter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 parameters and no output schema, the description is insufficient. It does not explain pagination behavior, default values, or the structure of the returned data. The tool seems incomplete for an agent to use effectively without additional knowledge.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 20% (only 'account' has a description). The description lists the filter names but provides no explanations for their semantics (e.g., what 'busca' searches). This minimal addition does not adequately compensate for the low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Lista produtos cadastrados' (list registered products), using a specific verb and resource. It also lists the filter parameters, making it distinct from get_product which fetches a single product.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing products with filters (tamanho_pagina, pagina, busca, ativo), but does not explicitly contrast with sibling tools like contaazul_get_product or provide when-not-to-use scenarios. No alternatives are named.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's mention of listing and filters adds limited behavioral context. It does disclose bulk execution support, but otherwise no additional behavioral traits beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, front-loading the purpose. It efficiently communicates the main filters and bulk capability. Minimal waste, though the filter list could be more structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers key filters but omits the 'account' parameter and provides no return format hints. Given no output schema, the agent lacks information about the response structure. The tool has 8 parameters, and while most are addressed, completeness is moderate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at only 25%, the description adds significant meaning by listing parameter names and providing enum values for 'status' (PENDENTE, PAGO, ATRASADO). It also introduces cliente_ids for bulk mode. This compensates for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Lista contas a receber' (Lists receivables), using a specific verb and resource. The tool name and description uniquely identify this as a listing operation for receivables, distinguishing it from sibling list tools for other entities like payables or installments.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists available filters and mentions bulk support, but it does not provide explicit guidance on when to use this tool versus alternatives such as contaazul_list_payables or contaazul_list_installments. Usage context is implied but not clearly delineated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so base safety is clear. The description adds valuable behavioral details: date format (YYYY-MM-DD), pagination parameters, and bulk support via cliente_ids. This goes beyond annotations and helps the agent understand operational constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler. The first sentence front-loads the purpose and key filters. The second sentence introduces bulk support. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For 8 parameters and no output schema, the description adequately covers input filters and bulk mode. However, it does not describe the return structure (e.g., what fields are in each sale object, pagination metadata like total count). This leaves some gaps for an agent to fully understand the tool's output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25%, with only 2 of 8 parameters having schema descriptions. The description compensates by listing all parameters and providing meaning: date format for data_inicio/data_fim, pagination concepts (tamanho_pagina, pagina), and bulk mode (cliente_ids). This adds crucial semantic value beyond the sparse schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Lista vendas' (list sales), which is a specific verb and resource. It lists filters, making the purpose clear. However, it does not explicitly distinguish from sibling tool 'contaazul_get_sale' which retrieves a single sale, though the filter set implies it is a list operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing to list sales with filtering by date, client, status, and pagination. It does not provide explicit when/when-not or alternative tools, but the context of filters gives reasonable guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds no additional behavioral context, such as pagination behavior, search logic, or any side effects. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but lacks detail. It could benefit from a brief mention of parameters or usage context without becoming verbose. It is minimally structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 parameters and no output schema, the description is severely incomplete. It does not mention return values, pagination, or filtering behavior, leaving significant gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool description does not explain any parameters. With 4 parameters and only 25% schema description coverage, the description fails to compensate. It adds no value beyond what minimal schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Lista serviços cadastrados' clearly states the tool lists registered services, matching the name 'list_services'. It distinguishes from sibling list tools that focus on other entities like accounts, contracts, etc. However, it lacks specificity about scope, such as whether it lists all services or filtered ones.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not mention when to use this tool over alternatives like other list tools or when not to use it. Given many sibling list tools exist, this omission leaves the agent without guidance.

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

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

The description adds no behavioral context beyond what annotations already imply (not read-only, not idempotent). The note 'data em JSON' gives a format hint but does not disclose side effects, permissions, or rate limits. With annotations already present, the bar is higher, yet the description contributes little.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and front-loaded, containing only two fragments. It wastes no words but may be too terse for a creation tool. Every sentence serves a purpose, but more detail could improve clarity without significant bloat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool creates a payable with a required JSON 'data' parameter and no output schema, the description fails to explain the expected structure of 'data', return values, or error handling. For a creation tool, this is insufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%: only 'account' has a description. The description adds 'data em JSON' for the 'data' parameter, providing a format hint. However, it does not explain the structure or constraints of 'data', leaving the agent to assume JSON format. This adds some value but is insufficient for complete comprehension.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Cria uma conta a pagar' (Creates a payable account), clearly identifying the action (create) and resource (payable). It distinguishes from sibling tools like 'contaazul_receivable_create' by specifying the type of account.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as 'contaazul_receivable_create' or updating existing payables. The description lacks prerequisites, context, or exclusion criteria.

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

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

The description reinforces the destructive nature already indicated by the `destructiveHint` annotation, adds a confirmation guideline, and discloses bulk execution support. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences that front-load the core purpose and then add bulk support. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple delete tool with annotations and schema providing most context, the description adds the critical destructive warning and bulk capability. However, it could mention return values or error handling, but that is not essential given tool simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 67% of parameters with descriptions (ids and account). The description mentions bulk support via ids but does not elaborate on the account parameter or add significant extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Remove uma pessoa por id' (delete a person by ID) and mentions bulk support. It distinguishes from sibling tools like create, update, get, and list operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description warns that it is a destructive operation and advises confirmation. However, it does not provide explicit guidance on when to use this tool versus alternative deletion/cancellation tools in the sibling list, nor does it mention prerequisites or side effects.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's claim of create/update adds little beyond that. No additional behavioral details (e.g., permissions, side effects) are provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loads the main purpose, and covers key points. The flattened action note is somewhat technical but not overly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is moderately complex (create/update with bulk), but the description lacks details on error behavior, response format, or idempotency. No output schema exists, so more context would be helpful. Adequate but with gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds value by specifying required fields for create (nome, cpf/cnpj) and the role of id and ids for update/bulk. This goes beyond the generic schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Cria ou atualiza uma pessoa' but the tool name and the note '[Flattened action: create]' conflict with sibling tool 'contaazul_person_write_update'. This ambiguity reduces clarity; the intended purpose is likely create-only but is not clearly distinguished.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use create vs update based on the action parameter and mentions bulk support, but it does not explicitly state when not to use this tool (e.g., in favor of the update sibling). Usage guidance is implied but not comprehensive.

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

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

Annotations indicate non-readonly and non-destructive, and description adds basic behavior (required fields per action) but lacks details on merge behavior, validation, or what happens on conflict.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is relatively concise but includes unnecessary detail ('Flattened action: update') and could be better organized, e.g., separating create and update guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Does not address how the tool determines whether to create or update (e.g., presence of 'id'), nor explains the 'account' parameter usage or error conditions; bulk support is mentioned but not detailed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover 100% of parameters, and the description adds value by specifying required fields within the 'data' JSON for create vs update, and mentions bulk support for 'ids'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states it creates or updates a person, but the presence of a sibling create tool (contaazul_person_write_create) and the note 'Flattened action: update' introduce ambiguity about whether both actions are truly supported.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives; the sibling create tool is not mentioned, and the description implies it handles both create and update, leaving the agent without clear selection criteria.

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

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

Annotations provide no behavioral hints (all false). The description adds that the tool supports bulk execution via 'ids' and differentiates create and update actions. It does not disclose authentication needs, rate limits, or idempotency (though idempotentHint is false). The '[Flattened action: create]' note is unclear and may mislead.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (3 lines) and uses a mix of Portuguese and English. It front-loads the core purpose and action details. The note '[Flattened action: create]' is a bit cryptic but does not add significant clutter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 4 parameters and no output schema, the description covers the main behaviors (create/update, bulk, account). However, it lacks details on error handling, return values, and the meaning of '[Flattened action: create]'. This leaves some gaps for an agent to fully understand tool usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75% but the description adds meaningful constraints beyond the schema: for action=create the 'data' must include nome and valor_venda, and for action=update the 'id' is required. This helps an agent understand mandatory fields per action, which the schema alone does not indicate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool creates or updates a product ('Cria ou atualiza produto'), and distinguishes between actions with required fields. However, the presence of a sibling 'contaazul_product_write_update' and the note '[Flattened action: create]' introduces ambiguity about whether it handles both actions or only create, slightly reducing clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage guidance by specifying required fields for create (nome + valor_venda) and update (id). It mentions bulk support for multiple ids. However, it does not explicitly compare to the update-only sibling nor provide when-not-to-use guidance, leaving some ambiguity 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.

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

Annotations already indicate not readonly and not destructive. The description adds context about bulk execution and flattened action, but does not disclose additional behavioral traits like side effects, permissions, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, with three clear sections that front-load the main purpose. Every sentence provides essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core functionality and bulk support but omits details about error handling, response format (no output schema), and the existence of a separate create tool that might be simpler for pure creation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains what should be inside the 'data' parameter for create vs update and clarifies the role of 'id' and 'ids'. This adds significant meaning beyond the schema, especially since 'id' has no schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Cria ou atualiza produto' and specifies conditions for create vs update. However, it does not differentiate from the sibling tool 'contaazul_product_write_create', which is dedicated to creation only, potentially causing confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides conditions for when to use create vs update (required fields in data) and mentions bulk support via ids. However, it does not explicitly guide when to use this tool over the dedicated create tool 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.

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

Annotations indicate readOnlyHint=false and destructiveHint=false, which are consistent with a creation operation. The description adds the hint that 'data' must be in JSON format, but does not disclose other behavioral aspects like side effects, permissions, or response handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise with one sentence and a code fragment, containing no wasted words. However, it may be too minimal for a creation tool, missing important details that could be included without significant length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool creates a receivable with two parameters and no output schema, the description lacks necessary context such as expected JSON structure, response details, prerequisites, or examples. This is insufficient for an agent to use confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 50% schema description coverage, the description adds meaning for the 'data' parameter by specifying it must be a JSON string. For 'account', the schema already describes it. This is adequate but not comprehensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Cria uma conta a receber' clearly indicates the action (create) and resource (receivable account). It distinguishes from sibling tools like 'contaazul_payable_create' and 'contaazul_list_receivables' through the verb and resource naming, though it does not explicitly state alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not specify when to use this tool versus siblings, nor does it mention any prerequisites or context for creation.

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

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

The description adds that the operation is destructive and requires confirmation, complementing the annotations' destructiveHint: true. It introduces bulk support behavior, providing useful context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with three short sentences. It is front-loaded with the purpose, followed by behavioral warning and bulk support. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core purpose and key behavior (destructive, bulk) but does not explain return values or the 'account' parameter in detail. Given no output schema and moderate complexity, it is minimally adequate but could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions bulk support via 'ids', which aligns with the schema description. It does not add new information about the 'id' or 'account' parameters beyond what the schema provides. The schema coverage is 67%, and the description adds moderate value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Cancela uma venda' clearly indicating the verb and resource. It does not explicitly distinguish from sibling tools like 'contaazul_contract_cancel' but the name provides sufficient context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises that it is a destructive operation and to confirm before proceeding. It also mentions bulk support. It provides clear context for usage but does not specify when not to use or alternative tools.

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

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

Annotations already indicate non-read-only. The description adds context about batch execution but does not disclose other behavioral traits like error handling, idempotency, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three sentences. It is front-loaded with the primary purpose, though the 'Flattened action: create' line seems extraneous.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks details on error responses, prerequisites, and differentiation from sibling tools. Given the tool handles both create and update, the absence of output schema and usage context reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to 'data' (full sale payload in JSON) and explains the role of 'id' and 'ids' in create/update and bulk modes, beyond the schema's coverage of only 50%.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates or updates a sale, with specific API endpoints. However, the name 'write_create' and sibling 'contaazul_sale_write_update' suggest the tool is for create only, causing potential confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage patterns based on action and mentions bulk support, but does not differentiate when to use this tool versus the sibling 'contaazul_sale_write_update'. No explicit when-not or alternatives guidance.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the description should disclose behavioral traits beyond these. It mentions endpoints and bulk support, but lacks details on mutation effects, authorization needs, error handling, or whether updates are partial or full replacements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively brief at three sentences, but the line '[Flattened action: update]' is cryptic and adds unnecessary confusion without explanation. It could be more efficient while maintaining clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write tool with 4 parameters, no output schema, and 50% schema description coverage, the description is incomplete. It does not explain the return value, error conditions, authentication requirements, or how the tool decides between create and update operations. Significant gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (ids and account have descriptions). The description adds semantics for 'data' (payload completo em JSON) and 'ids' (bulk execution), but does not clarify the role of 'id' versus 'ids' or how 'account' is used. With 50% coverage, the description partially compensates but is not comprehensive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it creates or updates a sale, which is a clear verb+resource. However, it is internally contradictory: it mentions 'action=create' and 'action=update' but also says 'Flattened action: update'. Moreover, it does not distinguish itself from the sibling 'contaazul_sale_write_create', which likely performs only creation. This reduces clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is provided on when to use this tool versus alternatives like 'contaazul_sale_write_create' or when not to use it. The description implies it supports both create and update, but does not explain how the action is determined or specify prerequisites.

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

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

Annotations indicate readOnlyHint=false (write operation) and destructiveHint=false. The description adds no behavioral traits beyond stating creation. It does not mention side effects, authorization needs, 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with the purpose front-loaded. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and only two parameters, the description is too brief. It does not explain what a service is in the Conta Azul context, return value, or error scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds value for the data parameter by noting it is JSON with nome, valor, etc., which is absent from the schema. The account parameter is already documented in the schema. Overall, 50% schema coverage gives a baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Cria um serviço' (Creates a service), specifying the verb and resource. However, it does not differentiate from sibling write tools like contaazul_contract_write or contaazul_person_write_create, which is a minor gap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites, use cases, or when it might be inappropriate.

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

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

Annotations indicate readOnlyHint=false but the description does not elaborate on side effects, reversibility, or required permissions for settling an installment.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two lines, no wasted words. It front-loads the purpose and then explains the critical parameter format.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core purpose and parameter data format but omits the optional 'account' parameter and any return value information. Given no output schema, more completeness would help.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description specifies that 'data' must be a JSON string containing 'parcela_id', 'conta_financeira_id', 'valor_pago', and 'data_pagamento', which adds significant value beyond the schema's generic string type. However, the 'account' parameter is not mentioned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Quita (settle) uma parcela', with a specific verb and resource. It distinguishes from the sibling tool 'contaazul_unsettle_installment'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'contaazul_unsettle_installment'. The description lacks context for usage decisions.

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

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

The description is minimal and does not add behavioral context beyond the name. Despite annotations providing destructiveHint=false, the tool is a mutation and no further detail is given about effects, permissions, 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, front-loading the core purpose. No extraneous wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters and no output schema, the description is too brief. It lacks details on prerequisites, error handling, return values, and the role of the 'account' parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67%, below the 80% threshold. The description only reiterates the 'id' and 'ids' parameters, adding no new semantics. The 'account' parameter is not mentioned in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Desfaz' (undoes) and the resource 'quitação' (settlement/installment). It distinguishes from the sibling tool 'contaazul_settle_installment' which performs the opposite action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates it settles by id and supports bulk mode, but lacks explicit guidance on when to use or not use this tool versus alternatives. 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.

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

The description discloses that the tool is in beta and currently returns a mock for debug, which is valuable behavioral context beyond annotations. Annotations do not contradict, as they are generic (readOnlyHint=false, destructiveHint=false). No further details on side effects or permissions are given, but the mock status is a key transparency point.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: a single sentence with a lead beta warning, followed by bullet-like actions. Every word serves a purpose, and critical info (beta, mock) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and the tool's moderate complexity (3 params, beta status), the description covers the actions and mock limitation but omits expected return values, error handling, and operational details. It is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, providing baseline clarity. The description adds minimal value over the schema: it briefly reiterates the action enum and parameter purposes (query for search, mcp_id for install/uninstall) but does not expand on formats, constraints, or examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is a global MCP marketplace with three distinct actions: search, install, uninstall. It distinguishes itself from sibling tools (mostly financial and CRM tools) by focusing on MCP management.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The tool describes when to use each action: search for discovery, install to add, uninstall to remove. However, it does not provide explicit exclusion criteria or mention when not to use the tool, though no direct alternatives exist among siblings.

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

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

Annotations indicate idempotentHint: true, and the description adds behavioral context by specifying the need for conversation array, which aids in reproduction. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at two sentences, with no wasted words. It front-loads the purpose and immediately provides critical usage detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and lack of output schema, the description is complete. It covers what the tool does, how to use it, and what data to include for effective bug reproduction.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, baseline is 3. The description adds value by explaining the conversation array format (JSON array with role, content, tool_name for tool calls, truncation over 500 chars), improving parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' It uses a specific verb and resource, and clearly distinguishes from sibling tools, none of which are for reporting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage guidance by instructing to include the conversation array for reproduction. It implies context for use but does not explicitly exclude scenarios or mention alternatives, which are not needed given the unique purpose.

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

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

Annotations already declare read-only and idempotent. Description adds that it shows 'platform and adapter versions', providing specific information beyond the generic annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains the tool's output (platform and adapter versions). Could include format details, but sufficient for a simple version check.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters; schema coverage 100%. Baseline for zero parameters is 4, and description does not need to add parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'show' and resource 'MCP platform and adapter versions', clearly distinguishing from sibling tools that create, update, list, or delete entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use vs alternatives. It's a read-only version check, so usage is implied to be safe anytime, but no exclusions or context provided.

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

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

Annotations already provide readOnlyHint and destructiveHint. The description adds the specific return data (installed MCPs, connection status, catalog count), which is useful context beyond annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise, front-loaded with the verb 'Returns', and contains no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (no parameters, no output schema), the description provides sufficient context about what the tool returns. It could optionally mention that no input is needed, but it's already implied by empty schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and the schema coverage is 100% (empty). According to guidelines, 0 parameters warrants a baseline of 4. The description adds no parameter info but is not required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns toolkit state (installed MCPs, connection status, catalog count). It distinguishes from sibling tools like authenticate and connect, which are actions, while this is a read-only info tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing toolkit state, but does not provide explicit when-to-use or when-not-to-use guidance relative to other tools. No 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.