Conta Azul MCP

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description explains behavior: with no args returns a login link, with token logs in. It adds context about permanent vs. session connections 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?

The description is somewhat long but efficiently packs information about both methods of authentication. It is front-loaded with the purpose. Could be slightly tighter but remains 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?

The description explains how to invoke the tool but does not specify what it returns when token is provided (e.g., success message or error). Given no output schema, this missing detail reduces completeness. Siblings are not relevant for this 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?

The input schema has 0% coverage for the 'token' parameter. The description fully compensates by explaining that token is a JWT pasted by the user, and that calling without token returns a login link. This adds essential meaning.

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

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

The description clearly states the tool is for authentication, describing the login flow via browser and token usage. It distinguishes from sibling tools like 'connect' and others by focusing on IDE agent 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 provides explicit guidance on best practices (adding token to config for permanent connection vs. session-only paste). It explains when to provide token and when to call with no arguments. Lacks explicit exclusions but context is sufficient.

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 indicate readOnlyHint, idempotentHint, destructiveHint=false. The description adds no extra behavioral context (e.g., how 'next number' is determined, potential side effects). It is adequate given annotation coverage.

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

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

Single sentence is concise, but it is in Portuguese (may reduce clarity for non-Portuguese agents). No wasted words.

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

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

With no output schema and only one optional parameter, the description is too minimal. It does not specify return format, behavior when account is or isn't provided, or edge cases.

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

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

Schema description coverage is 0%. The sole parameter 'account' is not mentioned or explained in the description. The agent receives no guidance on its purpose or effect.

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 the next available contract number (specific verb+resource). However, it does not differentiate from siblings like 'contaazul_get_contract' or '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 guidance on when to use this tool versus alternatives (e.g., before creating a contract). The description lacks context for usage 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 already indicate it is a write operation (readOnlyHint=false), but the description adds no further behavioral details (e.g., whether it overwrites existing contracts, required permissions, or side effects). 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 very short (two sentences), but it lacks crucial information. It is concise, but conciseness should not come at the expense of completeness. It earns a 3 for being brief yet somewhat informative.

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

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

Given the tool has 2 parameters and no output schema, and exists among many sibling tools, the description is insufficient. It does not explain what constitutes a valid contract, what the response looks like, or how to use 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?

With 0% schema description coverage, the explanation that 'data' is a JSON payload provides minimal meaning but does not specify expected structure, required fields, or the purpose of the 'account' parameter. More detail is needed.

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) and identifies the 'data' parameter as a JSON payload. However, it does not distinguish this tool from siblings like contaazul_payable_create or contaazul_sale_write_create, which may also involve contract-like 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?

No guidance is provided on when to use this tool instead of alternatives, nor are there any prerequisites or exclusions mentioned. The description lacks context for appropriate usage.

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 (false) and non-destructive (false). The description adds the fact that it creates a new budget, but does not disclose side effects, permissions required, or what happens on conflicts (e.g., duplicate budgets). With annotations present, the description provides adequate but not extra behavioral context.

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

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

The description is a single sentence that efficiently conveys purpose and parameter details. It uses a front-loaded structure and parenthetical lists to organize information 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?

While the description covers the input parameter 'data' well, it does not mention the return value or behavior on success/failure. There is no output schema, so describing what the tool returns (e.g., created budget ID) would improve completeness. The tool has two parameters but the 'account' parameter is not described.

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 0% (only specifies type 'string' for 'data'). The description compensates fully by explaining the JSON structure inside 'data', including required fields (id_cliente, data_orcamento, itens[]) and optional ones (data_validade, id_vendedor, composicao_de_valor). This adds significant 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 'Cria um orçamento' (Creates a budget) and provides specific details about required and optional fields. It distinguishes the tool from siblings like 'contaazul_get_budget' and 'contaazul_delete_budgets', making the purpose unambiguous.

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

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

The description does not explicitly indicate when to use this tool versus alternatives, nor does it mention prerequisites (e.g., client must exist). Usage is only implied by the tool name and description, but no guidance on when not to use it or what alternative tools to consider.

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 set destructiveHint=true, and description adds that it's a batch operation and the API v2 lacks single ID deletion. No contradictions. Provides useful 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 concise sentences. First sentence states action and warns of destructiveness. Second explains the parameter and API context. No fluff, 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?

Core behavior is clear, but missing description for 'account' parameter. Also lacks details on success/failure outcomes, partial deletes, or return values. Adequate for a simple destructive tool but incomplete regarding parameters.

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

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

Description explains the 'ids' parameter as list of budget UUIDs, but does not mention the 'account' parameter. With 0% schema description coverage, the description should cover both parameters; it only covers one.

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 it deletes budgets in batch by ID, distinguishing it from other tools like contaazul_get_budget or contaazul_list_budgets. The mention of 'destructive operation' reinforces the purpose.

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 includes caution 'confirme antes' (confirm before) implying need for user confirmation, but does not explicitly compare to alternatives like single delete (which doesn't exist in API v2) or other deletion tools. However, it hints at when to use this batch approach over single delete due to API limitation.

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 destructiveHint: true, so the description adds value by mentioning bulk support ('accepts ids for batched execution'), which is not captured in annotations. The warning 'confirme antes' is a usage instruction, not new behavioral info.

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 with no wasted words. First sentence states primary action, second adds bulk capability. Efficiently 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 destructive operation with no output schema, the description covers core behavior and bulk support but omits details on return values, error handling, or behavior when both 'id' and 'ids' are provided. The 'account' parameter is unmentioned. Adequate but 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?

The description explains the 'id' parameter by stating removal by id, and adds meaning to 'ids' with bulk support. However, it does not address the 'account' parameter, leaving its purpose unclear. Given 0% schema coverage, partial compensation is adequate.

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 'Remove um contrato por id,' which is a specific verb+resource. However, it does not differentiate from sibling tool 'contaazul_terminate_contract,' so it loses a point for lack of distinction.

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

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

The description advises 'confirme antes' (confirm before) implying caution for destructive operation, but it does not explicitly state when to use delete vs. terminate or other alternatives, leaving ambiguity.

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 confirms the destructive nature already indicated by the annotation (destructiveHint: true). It adds value by mentioning bulk support and specifying that 'id' is a UUID, but does not disclose potential side effects on related data.

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

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

The description is concise with two sentences plus a bulk support line. It is front-loaded with the purpose, though the structure could be improved by separating parameter explanations and usage notes more clearly.

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 3 parameters, 0% schema coverage, no output schema, and a destructive nature, the description is incomplete. It fails to document the 'account' parameter and does not describe return values or behavior for batched execution.

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

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

Schema description coverage is 0%, so the description must compensate. It explains only the 'id' parameter as the UUID of the settlement. The 'ids' parameter for bulk is mentioned but not detailed, and 'account' is completely undocumented.

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

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

The description clearly states the tool removes a settlement by id, using the specific verb 'estorna'. It distinguishes from related tools like 'contaazul_get_settlement' and 'contaazul_update_settlement', but does not differentiate among other delete 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 provides minimal usage guidance, only noting bulk support and warning of destructiveness. It lacks advice on when to use this tool versus alternatives, and does not specify prerequisites or confirmation steps.

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 readOnlyHint=false and destructiveHint=false, and the description adds the integration date requirement. However, it does not disclose side effects, error states, permissions, or idempotency. The description adds some context beyond annotations but leaves gaps.

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

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

The description is two sentences: first states the main function, second explains the 'data' parameter and a requirement. It is concise, front-loaded, and 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?

The tool has 2 parameters, no output schema. The description covers the main purpose and one parameter but omits the 'account' parameter and return value details. For a creation tool, more completeness (e.g., output format, error handling) 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 coverage is 0% (no parameter descriptions in schema). The description explains the 'data' parameter (JSON with charge type, installment reference, optional max parcels) but does not describe the 'account' parameter. It adds partial value but misses one parameter.

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

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

The description clearly states the tool generates a charge (boleto, pix, payment link) from a receivable account, specifying the charge types (BANKING_BILLET, PIX_CHARGE, CREDIT_CARD). It distinguishes itself from siblings like contaazul_receivable_create, which likely creates a receivable rather than generating a charge.

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

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

The description mentions a prerequisite (integration must be created after March/2025), but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or when-not-to-use guidance. Usage is implied but not fully clarified.

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 the bulk execution trait but no further behavioral details (e.g., rate limits, error handling). 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 three short sentences, no redundancy, and front-loaded with the core purpose. 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?

For a simple read-only tool with annotations, the description adequately covers the purpose, prerequisite, and bulk behavior. Missing explanation of the 'account' parameter or return format, but overall 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?

The schema has 0% description coverage. The description explains 'id' and 'ids' for bulk but omits the 'account' parameter. Baseline for 0 params is 4, but partial coverage reduces to 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 the tool retrieves the current balance of a financial account by id, including bulk support. It distinguishes from sibling tools like listing tools by specifying 'por id' and referencing a separate list 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?

It tells the agent to get the id from contaazul_list_financial_accounts, providing a clear prerequisite. It does not explicitly say when not to use it, but the read-only and bulk nature is evident.

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, destructiveHint=false, and idempotentHint=true. The description adds the batch execution capability via 'ids', which is behavioral context beyond annotations. 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?

Two sentences, each serving a clear purpose: first explains the tool's function, second adds batch support. Front-loaded and 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 tool with 3 parameters and no output schema, the description is adequate but incomplete. It covers the core purpose and batch variant but omits the 'account' parameter and does not describe return values or error conditions.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'id' and 'ids' (batch) but does not describe the 'account' parameter, leaving 33% of parameters semantically undocumented.

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

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

The description clearly states 'Detalhe de um orçamento por id (itens, cliente, composição de valor)' which specifies the verb (get details), resource (budget by id), and scope (items, client, value composition). It distinguishes from sibling tools like 'contaazul_list_budgets' and 'contaazul_create_budget'.

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 explicitly mentions 'Bulk support: accepts ids for batched execution', providing clear context for when to use single vs batch requests. However, it does not explicitly state when not to use the tool or mention alternatives beyond the implicit sibling list.

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 cover safety. The description does not add further behavioral context (e.g., prerequisites or data freshness), but 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, short sentence that conveys the core purpose without any unnecessary words or repetition.

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?

While the description provides a high-level overview, it lacks parameter details and does not specify the exact return structure or edge cases (e.g., what happens if company is not active). Given the tool's simplicity, it is minimally adequate.

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

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

The schema has 0% description coverage for the single 'account' parameter. The description does not explain what the parameter is for, leaving the agent to guess its meaning or format.

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 retrieves active company data including CNPJ, corporate name, and tax regime. It uses a verb+resource structure ('Dados da empresa') and is distinct from sibling tools like get_person or get_sale.

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. It does not specify context such as required authentication or typical scenarios, leaving the agent without decision support.

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 readOnly, idempotent, non-destructive. The description adds context about returning specific fields and batch execution, which is helpful and 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?

Two concise sentences with no wasted words. Could be slightly more structured, but it's efficient and front-loaded with the main purpose.

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

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

With no output schema, the description lists returned details (client, terms, etc.) which is adequate. It also covers bulk execution. Minor gap: no mention 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?

Description explains 'id' and 'ids' usage but fails to describe the 'account' parameter. Since schema description coverage is 0%, the description partially compensates but is incomplete.

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, listing the included information (client, terms, payment condition, value composition). This distinguishes it from sibling 'contaazul_list_contracts' which returns a list.

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 bulk support for multiple IDs but lacks explicit guidance on when to use this tool vs alternatives like list_contracts or contract_next_number.

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. Description adds behavioral detail that omitted dates use a wide window, which is not in 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 concise sentences covering purpose, parameters, and default behavior. No redundancy, 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?

Covers date parameters and default, but lacks description of account parameter and return format. Given no output schema, some return structure context would be helpful for a complete understanding.

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

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

Schema description coverage is 0%. Description explains data_inicio and data_fim with format details, but does not describe the account parameter, leaving its meaning unclear. Partially compensates but incomplete.

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 it retrieves initial balances of financial accounts by period ("Saldos iniciais das contas financeiras por período"). Differentiates from siblings like contaazul_get_account_balance (likely current balance) and contaazul_list_financial_accounts, though no explicit alternative naming.

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

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

Provides date format guidance (YYYY-MM-DD or ISO date-time) and default behavior (wide window if omitted). Implicitly indicates when to use for period-specific initial balances, but lacks explicit when-not or alternatives.

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 safe read operation (readOnlyHint, idempotentHint, non-destructive). Description adds valuable info about bulk execution via ids array, exceeding annotation coverage.

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

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

Two short, front-loaded sentences. First states core purpose, second adds bulk execution detail. 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?

For a simple retrieval tool with strong annotations, the description covers primary usage. However, missing explanation of the 'account' parameter and any return value description. Adequate but not fully 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?

Description explains 'id' and 'ids' partially (by id, bulk support), but the 'account' parameter is not mentioned. With 0% schema description coverage, the description fails to fully document all 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?

Clearly states it retrieves details of an installment by id, with explicit bulk support. Distinguishable from sibling tools like listaazul_list_installments (list) and contaazul_update_installment (update).

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, such as listing installments or updating. Usage is implied but not stated.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds the batched execution capability (ids parameter), which is behavioral information beyond annotations. No contradictions found.

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

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

Two sentences, front-loaded with the primary purpose. The bulk support note is included succinctly. No redundant or 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?

The description covers the core retrieval action and batch support but lacks explanation of optional parameters (e.g., account), parameter interaction, or return value structure. Given no output schema, the returned data format is unclear. Adequate but with noticeable gaps.

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

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

Schema description coverage is 0%, so the description bears the burden. It hints that 'ids' is for batched execution but does not clarify the 'id' vs 'ids' relationship or the 'account' parameter. Minimal added meaning beyond the schema structure.

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 details of an NF-e by ID ('Detalhe de uma NF-e por id'). It distinguishes from sibling list tools (e.g., contaazul_list_invoices_nfe) by specifying it returns a detailed record for a given ID, and the bulk support note further defines 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?

The description mentions bulk support, implying use when fetching one or multiple invoices by ID. However, it does not explicitly contrast with the list tool for summary vs detail, nor specify conditions when to avoid using it. Implicit usage is clear but lacks explicit alternatives or exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds bulk execution behavior, which is helpful. No contradictions. It does not detail error handling but for a simple get operation it's adequate.

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 words, and the key information 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 tool's simplicity and the presence of annotations, the description covers the core usage. However, lacking an output schema, it does not describe the response format, which could be important. The context is adequate but not fully 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?

With 0% schema description coverage, the description partially compensates by mentioning 'id' and 'ids' for bulk. However, the 'account' parameter is left unexplained, and no additional context like formats or constraints are provided.

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 'Detalhe de uma pessoa por id' clearly states the tool retrieves details of a person by ID, and the bulk support note distinguishes it from the list tool. It's 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 mentions bulk support with ids, indicating when to use it. However, it does not explicitly state when not to use it or compare to the list tool. The context is clear enough.

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 readOnly and idempotent. Description adds bulk execution via 'ids' array, providing behavioral 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?

Two sentences, front-loaded with core purpose, followed by bulk support note. No wasted 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?

Given no output schema and no parameter descriptions in schema, the description lacks details on response format, error handling, and the 'account' parameter. Incomplete for a tool with 3 parameters and output ambiguity.

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

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

With 0% schema coverage, the description adds meaning for 'id' and 'ids' (bulk support), but does not explain the 'account' parameter. Provides marginal help beyond 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 it retrieves a sale detail by ID, and mentions bulk support. It distinguishes from sibling tools like list_sales (listing) and sale_cancel (cancellation).

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 a specific sale ID is known, but does not explicitly contrast with alternatives like list_sales for browsing. Clear context but no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, telling the agent it is a safe read operation. The description adds the important behavioral trait of bulk support (accepting an array of ids), which is valuable context 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?

The description is two sentences, front-loading the core purpose and then adding the bulk support note. Every sentence adds value, with no superfluous words. Excellent 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 the low complexity and good annotations, the description provides the essential purpose and bulk support. However, it lacks details on return value (what fields are returned) and error handling, and does not explain the account parameter. For a simple get tool, this is adequate but not fully 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 input schema has 3 parameters (id, ids, account) with 0% schema coverage. The description only explains id (UUID of settlement) and alludes to ids for bulk support, but does not explain the account parameter at all. This leaves a significant gap, as the agent cannot understand how to use the account parameter.

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

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

The description clearly states 'Detalhe de uma baixa por id' which means detail of a settlement by id. It distinguishes from sibling tools like list_settlements (which lists all) and delete/update mutations, making its purpose 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 explicitly says to use this tool when you have an id and need the detail, and mentions bulk support for batched execution. It implicitly suggests using list_settlements when you don't have an id, but doesn't explicitly state when not to use. This is adequate for a simple read operation.

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 bar is low. The description adds that returned items include company_id and label, which is useful but not a behavioral trait 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 a single sentence, concise, but fails to cover parameter semantics. It earns its place for purpose, but the missing param information reduces conciseness 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?

No output schema or parameter descriptions exist. The description only indicates return field names but not their structure or types, and omits parameter explanation. Given the complexity (one optional parameter), the description is incomplete for safe use.

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

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

With 0% schema description coverage, the description must explain parameters. It does not mention the 'account' parameter at all, leaving its purpose ambiguous.

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 companies linked to the install, specifying the returned fields (company_id, label). This directly addresses the tool's purpose and distinguishes it from sibling list tools like lista_people or lista_products.

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 retrieving accounts associated with the current installation, but does not explicitly state when to use this tool versus alternatives, nor does it provide any 'when not to use' 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that results are paginated ('Paginado'), which is a behavioral trait. However, it does not explain pagination details like default page size or behavior when parameters are omitted. Overall, it adds some value 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?

The description is very short and front-loaded: the first part states the purpose, and 'Paginado' adds key info. Every word is useful. However, it could be slightly expanded to include parameter hints without becoming verbose. Overall, 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?

Given the tool has 3 parameters with no schema descriptions, no output schema, and minimal description, the description is incomplete. It does not explain how to use the parameters, the pagination behavior, or the response format. The mention of fields is helpful but insufficient for an agent to invoke it correctly 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 0%, meaning parameter descriptions are missing. The description does not explain any parameter (pagina, account, tamanho_pagina). It only implies pagination with 'Paginado' but does not clarify how the parameters relate. This fails to compensate for the lack of 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 clearly states the action 'Lista' (list) and the resource 'orçamentos' (budgets). It specifies the fields included: cliente, número, total, situação, versão. Among sibling tools, there are many list tools (e.g., contaazul_list_accounts, contaazul_list_contracts), but this tool explicitly targets budgets, distinguishing it well.

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. It does not mention prerequisites, scenarios where it is appropriate, or exclusions. For example, it does not compare with contaazul_get_budget or other list tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. However, the description adds no additional behavioral context beyond these, such as authentication needs, rate limits, or pagination behavior. The description does not contradict annotations, but offers no extra value.

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 of only 4 words, which is overly minimal. While concise, it omits critical information that could be added without significant verbosity. Essential details about parameters, output, and usage are missing, making the description inadequate for effective tool use.

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 4 parameters, no output schema, and multiple sibling tools with similar names, the description is extremely incomplete. It does not explain parameter functions, return format, or how to interpret results. An AI agent lacks sufficient context to use this tool correctly or efficiently.

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 4 parameters (tipo, pagina, account, tamanho_pagina) with 0% description coverage. The description provides no information about any parameter, their meanings, or usage. Since schema coverage is low, the description should compensate but fails entirely, leaving the agent to guess parameter purposes.

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 categorias financeiras (DRE)' clearly specifies the verb 'list' and the resource 'financial categories (DRE)'. It distinguishes from sibling list tools like 'contaazul_list_accounts' by naming the specific entity type. However, the acronym 'DRE' is not explained, which may reduce clarity for non-Portuguese agents.

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 other list tools for different entities. There is no mention of prerequisites, context, or exclusions. The agent receives no help in deciding to invoke this tool over similar ones.

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=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about pagination and that only IDs are returned, which is beyond annotation coverage.

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

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

Two sentences, each essential: first states purpose and key parameters, second covers pagination and follow-up tool. 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 listing tool with pagination, the description covers purpose, parameters, pagination, and return format. Could add default pagination size or total count info, but sufficient for effective use.

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 0%, but description explains date formats (YYYY-MM-DD or ISO) and mentions pagination. However, 'account' parameter is not described, leaving some ambiguity.

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 lists IDs of changed financial events for incremental sync/reconciliation, distinguishing it from other tools like contaazul_get_installment which provides details.

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?

Explicitly mentions use for incremental sync/reconciliation and advises using contaazul_get_installment for details, providing clear when-to-use and alternative 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?

Discloses that date parameters are required in API but optional here with wide window fallback, and notes missing functionality. Annotations already indicate read-only, idempotent, non-destructive; description adds useful context without contradiction.

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?

Concise, well-structured description that front-loads the main action, then lists filters, API limitations, and bulk support. 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?

Covers key aspects: main action, parameters, API limitations, bulk support. Lacks explanation of return values, but acceptable for a list tool without output schema.

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

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

With 0% schema coverage, the description fully explains all 8 parameters: date range, pagination, client ID, text search, and bulk client IDs, providing format and constraints (max 50 per page).

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 contracts with date range and other filters, and distinguishes from missing individual get/cancel/delete endpoints, differentiating from sibling 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?

Provides guidance on when to use (listing contracts with date range) and notes API limitations (no individual get/cancel/delete), but could be more explicit about when to use alternatives like contaazul_contract_write.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. However, the description adds no extra behavioral context such as pagination behavior, output format, or rate limits. The agent gets no help 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 (3 words in Portuguese), but this sacrifices informativeness. It lacks structure and does not even include a period. It is more under-specified than concisely helpful.

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 list tool with no output schema and 3 undocumented parameters, the description should explain pagination, filtering, and return value structure. It provides none of this, leaving the tool's behavior largely opaque.

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

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

Schema description coverage is 0%, so the description must compensate. It does not mention any of the three parameters (pagina, account, tamanho_pagina) or their meanings, leaving the agent without essential usage 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 'Lista centros de custo' clearly states the verb (list) and resource (cost centers). Although it does not explicitly differentiate from siblings, the unique resource name sufficiently distinguishes it.

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. There is no mention of prerequisites, filtering, or context where other list tools might be preferred.

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, destructiveHint=False, idempotentHint=True, which are clear. The description adds minimal context (listing types), but does not disclose pagination behavior, required permissions, or response format.

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

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

The description is a single concise sentence that immediately conveys the tool's purpose, with 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?

Given the lack of parameter descriptions and output schema, the description is insufficient to fully understand how to use the tool. It should at least explain the parameters and 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?

Schema coverage is 0%, and the description provides no explanation of the parameters (pagina, account, tamanho_pagina), leaving their meaning and usage entirely 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 it lists financial accounts and provides specific types (bank, cash, card). However, it does not differentiate from the sibling tool contaazul_list_accounts, which likely has a similar purpose.

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

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

No guidance on when to use this tool vs alternatives, such as when to use this specific list tool instead of other list tools for accounts or other entities.

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, indicating safe read. Description adds context that API v2 lacks bulk listing, reinforcing per-event scope. No contradiction, and it enhances transparency about limitations.

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, front-loaded with key info (lists installments of one event) and usage guidance. 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?

Tool is simple (2 params, no output schema). Description covers main behavior and usage context but omits details on the 'account' parameter and return format. Adequate but not fully complete given minimal schema support.

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 has 0% description coverage. Description mentions 'passe id_evento' clarifying the required parameter, but the optional 'account' parameter is unexplained. Only partial semantic value beyond 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 it lists installments of a single financial event, requiring 'id_evento'. It distinguishes from sibling tools that list all receivables or payables, making the purpose unambiguous.

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

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

Explicitly states when to use this tool (for a specific event) and when not (for sweeping all items), directing to sibling tools contaazul_list_receivables and contaazul_list_payables. Provides clear alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds no behavioral information such as pagination behavior, result ordering, or error conditions. The filter list is more about parameters than behavior.

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

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

The description is a single sentence with a clear listing of filters. It is efficient and front-loaded with purpose.

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 6 parameters, no output schema, and many similar siblings, the description lacks details on date formats, status values, pagination limits, and when to use this over other list tools. It is minimally complete but leaves significant gaps.

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

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

The description lists 5 of the 6 parameters by name (missing 'account'), which provides basic meaning over the schema's empty descriptions. However, no details on types, formats, or allowed values are given, which is limited given 0% 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 the tool lists issued invoices (NF-e) and mentions filters. It is specific about the resource and action, but does not differentiate from sibling list tools available.

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_list_sales or contaazul_get_invoice_nfe. No exclusions or when-not-to-use 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, destructiveHint=false. The description adds behavioral details: the maximum 15-day window, default date range, and possible enum values for status and tipo_negociacao. 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?

The description is two sentences: the first states the purpose clearly, the second details the key filters and constraints. It is concise with no wasted words, and front-loads essential 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 tool has 13 parameters and no output schema, the description should cover more. It explains the main filters and date behavior but misses pagination and account parameter context. The agent may be uncertain about paging or account usage, making it somewhat 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 0%, so the description must compensate. It explains the meaning and usage of about 10 out of 13 parameters, including enum values for status and negotiation type. However, it omits pagination parameters (pagina, tamanho_pagina) and the account filter, leaving some ambiguity.

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 'Lista NFS-e (notas fiscais de serviço) por filtro', providing a specific verb (list) and resource (NFS-e). It distinguishes effectively from sibling list tools (e.g., contaazul_list_invoices_nfe for different invoice types) by name and resource description.

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 the essential date parameters and default behavior (max 15-day window, last 15 days if omitted), and lists other optional filters. However, it does not explicitly state when not to use this tool or suggest alternatives among siblings, but the context is sufficient for an agent to select appropriately.

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, destructiveHint=false, idempotentHint=true. The description adds minimal behavioral context beyond listing filters; no mention of pagination behavior, rate limits, or other traits.

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

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

Description is a single sentence with parenthetical details for filters. It is front-loaded and efficient, though the parenthetical is somewhat dense.

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, no output schema, and no required params, the description should explain the return format or pagination behavior. It lacks details on output structure, max page size, or field descriptions.

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

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

Schema description coverage is 0%. Description covers 5 of 6 parameters (missing 'account') and provides date format and status values, but does not explain 'pagina' or 'tamanho_pagina' semantics beyond being filters.

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 verb 'Lista' and resource 'contas a pagar' (accounts payable). The resource name inherently distinguishes it from siblings like receivables, but no explicit differentiation is provided.

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 filters and notes default behavior (lists all if date filters omitted), but does not provide guidance on when to use this tool versus alternatives like contaazul_list_installments or contaazul_list_receivables.

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 safety profile is clear. The description adds no further behavioral details (e.g., pagination defaults, sorting, or that it returns all people if no filters are applied). It is adequate but does not enrich 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?

Two sentences: the first states the main purpose, the second lists filters. No wasted words, easy to scan. It is appropriately sized for the tool's simplicity.

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 doesn't detail the return format. It covers the essential types and filters. It could mention default pagination or behavior when no filters are applied, but for a simple list tool it is reasonably 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 parameter coverage is 0%, so the description carries the burden. It explains 5 of 6 parameters, including the non-trivial 'busca' as search by name/document. However, the 'account' parameter is not mentioned, leaving a gap.

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

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

The description clearly states it lists registered people and enumerates the types (clientes, fornecedores, vendedores, transportadores). The verb 'Lista' is specific and distinguishes from sibling tools like get_person (singular retrieval) and other list tools for different resources.

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 when to use—when you need a list of people with optional criteria. It doesn't explicitly contrast with get_person or other list tools, but the context of sibling tools makes the differentiation clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, providing the key behavioral traits. The description adds no additional behavioral context beyond listing filters, which is adequate given the annotation coverage.

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

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

The description is very short (two sentences) and front-loads the purpose. However, it is incomplete by omitting one parameter, slightly reducing efficiency.

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 many sibling list tools and no output schema, the description lacks output context (e.g., return format, pagination details). The missing 'account' parameter further 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?

Schema description coverage is 0%, so the description must add meaning. It lists four filters (tamanho_pagina, pagina, busca, ativo) but misses the 'account' parameter. No explanations of parameter semantics are provided, making it incomplete.

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 produtos cadastrados' (Lists registered products), clearly indicating the verb and resource. However, it does not distinguish from sibling list tools beyond the resource name, which is distinct enough.

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 (e.g., other list tools). The description only lists filters, implying usage for filtered listing, but no explicit use cases or exclusions.

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

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

Annotations indicate read-only and idempotent behavior; description adds default behavior when date filters are omitted (lists all) and enumerates status options, providing some extra context.

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

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

The description is a single sentence with a clear list of filters; it is efficient but could be better structured with separate sentences for 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?

Lacks output description; no mention of returned fields or pagination behavior beyond parameter names. For a list tool with no output schema, this is a significant gap.

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

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

With 0% schema coverage, the description explains all 7 parameters except 'account', detailing date format, default behavior, and status enums, fully compensating for missing 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 clearly states the tool lists accounts receivable (revenue installments) and enumerates filters, distinguishing it from other list tools by resource name.

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 siblings like contaazul_list_payables or when not to use it; only functional description 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, destructiveHint=false, so the agent knows it's a safe read operation. The description adds bulk support and date format details but does not disclose pagination behavior or potential rate limits.

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

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

The description is concise with two sentences: first lists filters, second notes bulk support. No unnecessary words; key information 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 8 parameters and no output schema, the description lacks context on return structure (e.g., fields of each sale), pagination defaults, and maximum page size. This omission hinders an agent from fully understanding the tool's behavior.

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?

Since schema description coverage is 0%, the description compensates by listing most parameters (tamanho_pagina, pagina, data_inicio, data_fim with format, cliente_id, status_venda) and mentioning cliente_ids for bulk. However, it omits the 'account' parameter, leaving incomplete semantic 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 vendas' (list sales) and lists available filters, making the verb+resource unambiguous. It distinguishes from sibling tools like 'contaazul_get_sale' (single sale) 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 lists filters but does not explicitly state when to use this tool versus alternatives, nor does it provide guidance on typical use cases or exclusions. It is adequate for a simple list tool.

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 and destructiveHint, so safety is clear. However, the description adds no additional behavioral traits like pagination behavior or search semantics.

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

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

The description is a single sentence, which is concise, but it is under-specified for the tool's complexity.

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, 4 undocumented parameters, and no description of return values or pagination. The description is severely incomplete for effective use.

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 does not explain any of the 4 parameters (busca, pagina, account, tamanho_pagina). With 0% schema description coverage, this is a critical gap.

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

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

The description 'Lista serviços cadastrados' clearly states it lists registered services, but does not differentiate from sibling list tools like contaazul_list_products or contaazul_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?

No guidance on when to use this tool versus alternatives. The description is a single line without context on prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, making the safety profile clear. The description adds value by stating the bulk execution capability (accepts multiple IDs) and that it lists settlements for a specific installment. 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, consisting of two short sentences. The first sentence states the core purpose, and the second adds bulk support detail. No wasted words; front-loaded with essential 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 tool is a straightforward list operation with read-only annotations and no output schema, the description adequately covers the key behavior: it lists settlements for an installment, with batch support. It doesn't detail the output format, but that is acceptable without an output schema. Slightly more context on return structure could improve 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?

Schema descriptions are missing (0% coverage), so the description must compensate. It explains that 'id' is the UUID of the installment and mentions 'ids' for batch. However, it does not explain the 'account' parameter, leaving its purpose unclear. This is a partial improvement over 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 lists settlements of an installment, specifying the key parameter 'id' as the UUID of the installment. This distinguishes it from sibling tools like 'contaazul_get_settlement' (single settlement) and 'contaazul_list_installments' (list 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 indicates when to use this tool (to list settlements for a given installment) and mentions bulk support via the 'ids' parameter. However, it does not explicitly state when not to use it or provide alternatives, such as using 'contaazul_get_settlement' for a single settlement's details.

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?

Adds critical behavior beyond annotations: date format (YYYY-MM-DD), maximum window of 1 year, default period of last 365 days, and pagination. Annotations already indicate read-only and idempotent, so description enriches without contradiction.

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 in Portuguese, front-loaded with main purpose, followed by parameter constraints. No superfluous text; every phrase adds value.

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

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

Covers date parameters and pagination but omits the 'account' parameter entirely. No description of return results (though no output schema, a list operation could describe the nature of returned data). Adequate but not comprehensive for a 5-parameter tool.

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

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

With 0% schema coverage, description partially compensates by detailing data_inicio and data_fim (format and constraints) and mention of pagination. However, 'account' parameter remains undocumented, and not all parameters receive explanation.

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?

Clearly states 'Lista transferências entre contas financeiras' (lists transfers between financial accounts), specifying the verb and resource. Distinguishes from sibling list tools (e.g., list_accounts, list_financial_accounts) as the only tool for transfers.

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?

Mentions 'por período (conciliação)' (by period, reconciliation), indicating the context for use. No explicit alternatives or exclusions, but the purpose is clear enough that a user would know when to choose this tool.

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 value beyond annotations by disclosing the asynchronous nature (return 202 + protocolId/status) and specifying the return format. Annotations only provide basic hints (readOnlyHint: false, etc.), so the description effectively communicates key behavioral traits.

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

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

The description is a single sentence with a parenthetical listing fields, plus a short sentence on return. It is dense and front-loaded with the core action. Slightly more structure could improve readability, but it is efficient without 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 2 parameters, no output schema, and minimal annotations, the description covers purpose, data structure, return format, and async behavior. However, it omits any mention of the 'account' parameter and does not address errors or prerequisites. This leaves gaps for an AI agent to fully understand 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 0%, so the description must compensate. It explains that 'data' is a JSON string with the structure of EventoFinanceiroRequest, referencing fields. However, the 'account' parameter is not described at all. The addition for 'data' is helpful, but incomplete coverage of both parameters limits the score.

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 evento financeiro de conta a pagar' (creates a payable financial event), using a specific verb and resource. It distinguishes itself from the sibling tool contaazul_receivable_create by referencing its structure, making the purpose unmistakable.

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

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

The description provides clear context by noting the data structure is the same as contaazul_receivable_create and listing the fields. While it doesn't explicitly state when not to use it or offer alternatives, the reference to the receivable tool implies the distinction. Slight room for improvement with explicit exclusions.

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

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

Annotations already indicate destructiveHint=true; description adds explicit warning and bulk support. 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 short sentences, front-loaded with purpose and key warnings, no waste.

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?

Complete for a delete operation with destructiveHint: covers purpose, confirmation, bulk. No output schema but deletion typically returns success.

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

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

With 0% schema coverage, description explains 'ids' for batch execution but does not mention 'account' parameter. Adds some value but incomplete.

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?

Clearly states 'Remove uma pessoa por id' (remove a person by id), with bulk support. Distinct from siblings like get, create, update.

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?

Warns about destructive nature ('confirme antes') and mentions bulk execution. Could be more explicit about when to use vs alternatives, but sufficient.

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

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

The description goes well beyond annotations, detailing update merge behavior, null-clearing, and full validation by the API. This discloses important behavioral traits that annotations (readOnlyHint=false, destructiveHint=false) do not cover, with no contradiction.

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 efficient but includes a confusing note '[Flattened action: create]' that conflicts with the dual create/update claim. It could be more streamlined, but overall it packs necessary 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 actions, parameter details, and update caveats, but omits the return value (no output schema) and does not explain the 'account' parameter. This leaves moderate gaps given the tool's complexity.

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 0%, the description compensates by explaining the 'data' JSON structure, required fields for actions, and enums. However, the 'account' parameter is not mentioned, leaving a gap in parameter semantics.

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 person, but the tool name 'write_create' and the existence of a sibling 'contaazul_person_write_update' create confusion about the tool's specific purpose. It does not distinguish from the sibling update tool, leading to 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?

The description provides clear parameter requirements for create and update actions within this tool, but fails to explain when to use this tool versus the separate update sibling tool. It implies usage but leaves the agent without explicit guidance on tool selection.

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 significant behavioral context beyond annotations: partial update with null clearing, full-record validation by Conta Azul, potential missing-field errors, and bulk support via ids. No contradiction with annotations (readOnlyHint=false is correct for a write tool).

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

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

The description is moderately long but well-structured with clear action breakdown, bullet-like formatting for enums, and explicit warnings. Every sentence adds value, though some redundancy could be trimmed (e.g., repeated 'action=').

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 4 parameters, no output schema, and no nested objects, the description covers all aspects: input parameters, both actions with requirements, edge cases (null clearing, validation errors), and bulk execution. It is fully adequate for correct 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?

With 0% schema description coverage, the description fully compensates by explaining each parameter (id, ids, data, account), required fields per action, enums for tipo_pessoa and perfis, and the JSON data format. This provides comprehensive meaning beyond the bare 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 creates or updates a person (verb+resource) and distinguishes itself from sibling tools like contaazul_person_write_create (create-only) and contaazul_person_delete (delete).

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 explicitly explains when to use action=create vs action=update, detailing required fields and update behavior (partial merge, null clears). It also warns about Conta Azul's full-record validation and missing-field errors. It lacks explicit 'when not to use' but is clear enough given 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?

Discloses that the API lacks update and GET by id endpoints, which is important behavioral context beyond the annotations. Annotations are consistent (readOnlyHint=false, destructiveHint=false).

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 front-loaded purpose and essential usage context. No extraneous 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?

Covers the tool's purpose, required data format, and API limitations. No output schema exists, so missing response details is acceptable; however, a brief note on what the tool returns (e.g., created product ID) would slightly improve 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?

Adds meaningful context for the 'data' parameter by specifying required fields ('nome + valor_venda obrigatórios em `data` JSON'), compensating for 0% schema coverage. The 'account' parameter is not explained, but the main parameter is well described.

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 produto' with required fields, and distinguishes from the sibling tool 'contaazul_list_products' by noting that there is no update or GET by id, so for queries use the list 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?

Explicitly states when to use (to create a product) and gives alternative for querying ('contaazul_list_products'). Also clarifies that the API does not support update or GET by id.

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, consistent with a create operation. The description adds that it returns 202 and explains asynchronous processing, disclosing key behavioral traits 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?

Description is a single dense paragraph but front-loaded with purpose. It covers all necessary details efficiently, though could benefit from bullet points for readability. No waste.

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 complexity and no output schema, description covers most fields and async nature. However, it omits explanation of the 'account' parameter and error handling. Lacks some completeness for a create 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 0%, so description fully compensates. It details the 'data' JSON structure, listing all required and optional sub-fields with examples and UUID sources, adding significant meaning.

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

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

The description clearly states 'Cria um evento financeiro de conta a receber' which is a specific verb+resource. It distinguishes from siblings like contaazul_payable_create and related list tools by focusing on receivable creation.

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 context for when to use by listing mandatory fields and referencing sibling tools for lookups (e.g., contaazul_list_people). However, it lacks explicit when-not or alternative tool 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?

Adds value beyond annotations by stating 'operação destrutiva' and 'confirme antes', and by revealing bulk execution support. No contradiction with destructiveHint annotation.

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

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

Two sentences, no filler. Purpose and key warning are front-loaded. Every word serves a 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?

Lacks explanation of return value and the 'account' parameter. For a destructive tool with 3 params, more completeness is desirable, but the warning and bulk support are critical and 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?

Only explains the 'ids' parameter for batch execution. The 'id' and 'account' parameters are not described. With 0% schema coverage, more compensation is needed, but the description adds some meaning.

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

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

The description clearly states the tool cancels a sale, distinguishing it from sibling tools like cria/atualiza. The verb 'cancela' and resource 'venda' are specific. Bulk support further clarifies 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?

Explicitly warns it is destructive and requires confirmation, guiding appropriate use. Does not name alternatives or exclusions, but the context of cancellation vs. other sale operations is clear.

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

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

Annotations already indicate a write operation (non-read-only). The description adds HTTP endpoint details and batch execution support. It does not disclose side effects, authentication needs, or error behavior, so adds moderate value 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?

The description mixes Portuguese and English, has a redundant '[Flattened action: create]' line, and is not structurally clean. It could be more concise and better organized.

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

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

Given the tool's complexity (dual actions, batch support, 4 params with no schema descriptions, no output schema), the description is incomplete. It fails to differentiate between create and update usage, describe the 'id' parameter, or explain batch response behavior.

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 0%, so description must compensate. The description explains 'data' as JSON payload and 'ids' for bulk support, but does not clarify 'id' or 'account'. This provides partial but insufficient parameter documentation.

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 creates or updates a sale, specifying HTTP methods and endpoints. However, the tool name suggests 'write_create', yet the description includes update, which could cause confusion with the sibling tool 'contaazul_sale_write_update'.

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 HTTP endpoints for create and update, and mentions bulk support. However, it lacks explicit guidance on when to use this tool versus the separate update tool, and does not specify criteria for choosing between actions within this tool.

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 the description confirms mutation (create/update) and adds bulk execution capability. While annotations are sparse, the description provides useful behavioral context beyond them, including endpoints and bulk support, without contradiction.

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, using two sentences and a note to convey core purpose, action mapping, and bulk support. It front-loads the main function. The terms 'Flattened action: update' may cause slight confusion, but overall no redundant 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?

The tool has multiple modes and 4 parameters with no output schema. The description covers create/update distinction and bulk support, but fails to explain the data parameter structure, account parameter, or return values. This is adequate but not fully comprehensive for informed 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?

With 0% schema description coverage, the description adds meaning for parameters id (used for update), ids (bulk), and data (full JSON payload). However, it omits explanation for the account parameter and does not detail the structure or required fields of data, leaving gaps.

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

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

The description clearly states the tool creates or updates a sale, specifying the endpoints for each action. It distinguishes from sibling tool contaazul_sale_write_create by covering both operations, and mentions bulk support, making the purpose specific and differentiated.

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

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

The description explains that action=create uses /venda and action=update uses /vendas/{id}, providing basic usage context. However, it does not explicitly advise when to use this tool versus the sibling write_create for create-only operations, nor does it mention prerequisites or conditions for bulk usage.

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 this is a write operation (readOnlyHint=false, destructiveHint=false). The description adds 'cria' (creates) but does not disclose whether creation is idempotent, what happens on duplicate, required permissions, or side effects. Additional behavioral context is absent.

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—one sentence and a brief note about `data`. It is concise but at the expense of useful information. The structure is acceptable but could be expanded without becoming wordy.

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 2 parameters, no output schema, and exists among many sibling write tools. The description fails to explain the account parameter, expected return values, prerequisites (e.g., authentication), or provide a complete example. The vague 'etc.' does not 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?

Schema description coverage is 0%. The description states `data` is JSON with name, value, etc., which provides a minimal hint about the structure. However, the account parameter is not mentioned, and the exact format or required fields of the JSON are not specified. This adds only marginal 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 'Cria um serviço' clearly states the action and resource. It indicates that the tool creates a service, which distinguishes it from sibling tools like product_write or person_write_create. However, it does not explicitly differentiate from other write tools beyond the resource name.

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

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_product_write or contaazul_sale_write_create. The description lacks context for selection among the many write operations.

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 this tool creates a settlement record, returning a reconciliation ID. It mentions automatic version handling for concurrency. Annotations already indicate non-read-only and non-destructive behavior, and the description aligns with that, adding context about the composition of the data parameter.

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 plus notes on bulk support. It front-loads the main purpose and then details parameters. However, it could be more structured by separating parameter explanations.

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

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

Given the tool's complexity (multiple fields in 'data'), the description covers the core usage: obtaining IDs, constructing the payment JSON, and returning the settlement. It also mentions bulk support. However, it does not describe error handling, idempotency, or the separate 'account' parameter. With no output schema, the return value description is minimal.

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 for 'id' (UUID of the installment) and 'data' (JSON structure with required fields like data_pagamento, composicao_valor). However, it does not explain the 'account' parameter, which is separate from the 'data' JSON, and only vaguely mentions 'ids' for bulk support. Schema coverage is 0%, so description partially compensates.

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 records a settlement (recebimento/pagamento) for an installment. It specifies the resource (parcela) and the action (registrar baixa). It distinguishes from sibling tools like contaazul_update_installment or contaazul_delete_settlement.

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 this tool (to record payment for an installment) and how to obtain the required installment UUID from related tools (e.g., contaazul_list_receivables). It mentions bulk execution via 'ids' parameter. However, it does not explicitly state 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?

Beyond the annotation 'destructiveHint: true', the description discloses the operation is sensitive and requires confirmation, and highlights bulk execution support. This adds meaningful behavioral context.

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

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

The description is two short sentences, front-loaded with the primary action, and contains no unnecessary 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?

The description covers core purpose and sensitivity, but lacks explanation of the 'account' parameter and does not describe return values or effects on the system, leaving gaps 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?

With 0% schema coverage, the description compensates for 'id' and 'ids' but completely omits 'account'. This leaves a required parameter unexplained, reducing clarity for agents.

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 terminates a contract by ID, including bulk execution. However, it does not differentiate from the similar sibling tool 'contaazul_delete_contract', which may cause 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 warns that the operation is sensitive and advises confirmation, but lacks guidance on when to use vs. alternatives like deletion, or any context on prerequisites or post-conditions.

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, consistent with a PATCH update. Description adds behavioral context: the 'versao' field is automatically fetched for concurrency control, and bulk accepts 'ids'. 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?

Description is succinct with three sentences: first states purpose and fields, second gives alternative tool guidance, third mentions bulk. No fluff, all information 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?

While no output schema exists, the description covers parameter semantics, usage guidelines, and behavioral traits adequately for a PATCH update. Lacks explicit return value details, but the context is sufficient for an AI agent to invoke 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 0%, so description carries full burden. Lists all editable fields inside the 'data' JSON parameter (nota, descricao, vencimento, etc.), explains that 'versao' is auto-handled, and notes 'ids' for bulk. Provides crucial meaning not present in raw 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?

Clearly states 'Atualiza campos de uma parcela (PATCH)', specifying the resource (installment) and action (partial update). Distinguishes from siblings like contaazul_settle_installment and contaazul_delete_settlement by mentioning their different purposes.

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?

Explicitly tells when to use this tool (update fields) and when to use alternatives: for payment/baixa use contaazul_settle_installment, for reversal use contaazul_delete_settlement. Also notes bulk support for batched execution.

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, destructiveHint=false, which aligns with the description's update nature. The description adds behavioral context by stating that 'versao' is fetched automatically, hinting at optimistic concurrency control. However, it does not disclose error handling, idempotency, or side effects beyond the update.

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 short paragraphs. The first sentence immediately states the action and method. Every sentence adds value: parameter descriptions and bulk support note. 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 4 parameters, no output schema, and sparse annotations, the description provides adequate coverage for the update action and primary parameters. However, it lacks details on return values, error scenarios, and the 'account' parameter. The bulk support mention adds some 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?

Schema description coverage is 0%, so the description must compensate. It explains 'id' as UUID and 'data' as JSON with example fields (data_pagamento, etc.) and notes automatic version. However, it does not explain the 'ids' parameter thoroughly (only 'bulk support') and omits the 'account' parameter entirely.

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 'Atualiza' (update) and resource 'baixa' (settlement), and mentions it's a PATCH operation. It provides specific fields to update and notes automatic version fetching. However, it does not explicitly differentiate from sibling tools like 'contaazul_settle_installment', which might be related but is distinct.

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 bulk support via 'ids', implying usage for batch updates, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., creating a settlement or settling an installment). There are no exclusions or when-not recommendations.

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?

Despite minimal annotations, the description thoroughly outlines behavioral traits: invoke works even for uninstalled MCPs, returns connect links for credentials and checkout links for payments, and flags installation status. No contradictions with annotations; openWorldHint=true aligns with the tool's exploratory nature.

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 lengthy but well-organized, front-loading the tool's purpose and core flow. Every sentence contributes to understanding the complex multi-action behavior. Minor redundancy exists (e.g., repeated mentions of install vs invoke), but overall it earns its 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 no output schema and 15 parameters, the description covers essential aspects: actions available, authentication and payment handling, installation persistence, and admin requirements. It even addresses billing and bug reporting. The agent has sufficient context 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?

With 0% schema description coverage and 15 parameters, the description adds value by explaining how key parameters like action, query, mcp_id, tool_id, and arguments are used in the core flow. However, it does not systematically define every parameter (e.g., limit, conversation, request_name), leaving some gaps that the agent must infer.

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

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

The description clearly identifies the tool as the official marketplace and catalog for MCPs and tools. It explicitly states the core flow of search, describe, and invoke, and distinguishes itself from external registries with a 'use THIS tool FIRST' directive.

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

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

Provides explicit guidance on when to use this tool versus alternatives. It details the primary flow (search → describe → invoke), explains when to prefer invoke over install, and specifies that write actions require workspace owner/admin. This leaves little ambiguity for the 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 convey idempotency and non-destructiveness. The description adds that the tool submits feedback and expects conversation data, but does not detail backend behavior (e.g., ticket creation, confirmation). With annotations covering safety profile, additional context would be beneficial but is not required for adequacy.

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 extremely concise: two sentences, no redundancy. Front-loads the purpose and immediately provides key usage guidance. 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?

Given the tool has 3 parameters and no output schema, the description adequately covers purpose and key parameter guidance. Lacks details on return values or post-submission behavior (e.g., confirmation), but for a feedback tool, this may be sufficient. Completeness is above average but not fully comprehensive.

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

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

Schema description coverage is 0%, so description must compensate. It clarifies the 'conversation' parameter by specifying it should contain recent messages for reproduction, but does not explain 'context' or 'message' beyond basic meaning. This adds some value, 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?

Description explicitly states the tool's purpose: report a bug, missing feature, or send feedback. It clearly identifies the action (report) and the scope (bugs, features, feedback), distinguishing it from sibling tools that are mostly Contaazul operations or system tools.

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

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

Provides explicit instruction to include the conversation array for reproduction, guiding effective use. Does not explicitly state when to use versus alternatives, but the context implies this is for issue reporting rather than business operations.

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.