Conta Azul MCP

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

Annotations indicate idempotentHint=true, no destructive or readOnly hints. The description adds context beyond annotations: explains the two login modes (permanent vs session) and the browser flow. It does not contradict annotations and adds useful behavioral details.

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

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

The description is slightly verbose but every sentence provides value. It front-loads the main purpose and uses a colon to separate context from instruction. Could be slightly more terse, but still effective.

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

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

Given the lack of output schema, the description does not fully describe the return format. It mentions the link but not the response structure. For a simple auth tool, this is adequate but incomplete; a brief mention of the response object would 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?

The input schema has zero parameter descriptions (schema coverage 0%). The description compensates fully by explaining the 'token' parameter as a JWT and that calling without args returns a login link. This adds essential semantics missing from 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 specifies the tool's purpose: authentication for IDE agents via token. It uses specific verbs ('log in', 'copy', 'paste') and distinguishes from sibling tools which cover different functionalities like connecting, reporting bugs, or managing contracts.

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: for permanent config (add to header) or session-only login (call with token). Also explains the alternative of calling with no args to get a link. This clearly differentiates use cases.

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 context about the return value structure depending on the connection state, but does not reveal additional behavioral traits beyond what annotations provide.

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

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

Two sentences that front-load the main purpose and efficiently cover the two scenarios. No wasted words.

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

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

With no output schema, the description provides sufficient detail about the return format in the two main states. It could mention error cases or URL structure, but for a simple status check tool, this is adequately 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 0 parameters with 100% schema description coverage. The description compensates by explaining the return value semantics, which is valuable for an agent deciding whether to use this tool.

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

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

The description clearly states that the tool returns connection status and URLs, specifying two distinct states (all providers connected vs missing credentials). This is a specific verb+resource combination that distinguishes it from other tools like 'authenticate'.

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 on when to use the tool (to check connection status) and describes the behavior in different scenarios. While it does not explicitly name alternatives or say when not to use, the mention of missing credentials implies that 'authenticate' would be needed instead.

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 and idempotency. The description adds no behavioral traits beyond what annotations provide, but it does not contradict them either. The bar is lower due to good annotations, so a 3 is appropriate.

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

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

The description is a single sentence that directly states the tool's purpose with no extraneous words. It is optimally concise and 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 has one undocumented parameter and no output schema, the description should compensate by clarifying the parameter's role and the behavior of 'next available number' (e.g., global vs per account, sequential vs skipping). The current description leaves these gaps, making it incomplete for full 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?

The schema has one parameter 'account' with no description, and schema description coverage is 0%. The description does not explain what 'account' means, whether it is required or optional, or how it affects the result. This is a critical gap that severely hampers correct usage.

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 'Retorna o próximo número de contrato disponível' clearly states the verb (returns) and resource (next available contract number), making the tool's purpose understandable. However, it does not differentiate from sibling tools like 'contaazul_list_contracts' which might also return contract numbers, so it loses some points for lack of sibling 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 provides no guidance on when to use this tool versus alternatives (e.g., before creating a contract, after listing contracts). There is no mention of context or prerequisites, leaving an agent to infer usage on its own.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, but the description only repeats that it creates a contract. No additional behavioral traits are disclosed, such as side effects, required permissions, or idempotency.

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. It front-loads the purpose and adds a brief param hint. However, it could be better structured with separate sections for usage or parameters.

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 (2 params, no output schema), the description is incomplete. It lacks guidance on the payload structure, error handling, response format, and the account parameter's role.

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 provide meaning. It adds that 'data' is a JSON payload, but does not explain its structure or the optional 'account' parameter. This is minimal extra value.

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

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

The description clearly states 'Cria um contrato' (Creates a contract), specifying the verb and resource. It distinguishes from sibling tools like get, list, delete, and terminate contracts, but does not differentiate from other write tools like contaazul_sale_write_create.

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, context, or situations where this tool should be avoided.

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 (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that it creates a budget but does not disclose side effects, authentication needs, or failure modes.

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

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

The description is concise but a single paragraph. It could benefit from structural improvements like bullet points for clarity, but it remains efficient and to the point.

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?

Without an output schema, the description fails to mention return values or error conditions. It provides enough to construct the input but lacks completeness for a creation tool with nested items.

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 details the expected JSON structure for the 'data' parameter (id_cliente, data_orcamento, itens[], etc.), adding significant meaning beyond the bare schema. However, the 'account' parameter is not explained, 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 'Cria um orçamento' (creates a budget) and enumerates required and optional fields, distinguishing it from sibling create tools like contaazul_payable_create.

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 context (creating a budget) but provides no explicit guidance on when to use this tool vs alternatives (e.g., updating budgets) or when not to use it.

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

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

The description repeats the destructive nature already indicated by the annotation (destructiveHint=true). It adds the batch deletion behavior and the API version limitation, but these are minor additions beyond what annotations already provide. 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 extremely concise with only two sentences, no wasted words, and the core purpose is front-loaded. Every sentence provides 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?

For a batch delete tool with no output schema, the description covers the main action and the key parameter. It misses the 'account' parameter and does not describe return values, but overall it is reasonably complete for the task.

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 the 'ids' parameter as a list of UUIDs, which adds value. However, the 'account' parameter is entirely undocumented in both schema and description, 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 that the tool deletes budgets in batch by ID. It uses a specific verb ('Exclui') and resource ('orçamentos'), and the detail about the API v2 lacking single ID deletion distinguishes it from any potential single-delete 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 includes a warning ('confirme antes') implying caution, but does not explicitly state when to use this tool versus alternatives or provide exclusions. It notes the API limitation, which hints at context, but lacks formal usage guidance.

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

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

The description reinforces the annotation's destructiveHint with 'Operação destrutiva, confirme antes' and adds valuable behavioral detail about bulk execution ('Bulk support: accepts ids for batched execution'). This goes beyond what annotations provide, earning a high score.

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

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

The description is extremely concise—two short sentences that front-load the primary action and follow with critical warnings and bulk capability. Every sentence adds value with 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 the tool's destructive nature, three parameters, and no output schema, the description lacks crucial context such as parameter descriptions, error handling, return value, and irreversibility warnings beyond the basic 'confirme antes'. This gap impacts an AI agent's ability 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?

With schema description coverage at 0%, the description should compensate but only briefly mentions 'id' and 'ids' without explaining their format, constraints, or the 'account' parameter (which is completely undocumented). This leaves the AI agent without needed 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 action ('Remove um contrato por id') specifying the verb and resource. The mention of bulk support with ids gives additional detail. However, it does not explicitly differentiate from the sibling tool 'contaazul_terminate_contract', which may involve a different operation, preventing a top score.

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

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

No guidance is provided on when to use this tool versus alternatives like 'contaazul_terminate_contract' or other write operations. The warning 'confirme antes' indicates caution but does not specify context or prerequisites.

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

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

Annotations already declare destructiveHint=true, so the description's mention of 'operação destrutiva' adds no new behavioral insight. It adds the concept of bulk support and the need for confirmation, but does not detail side effects, permissions, or rate limits. The description provides marginal additional 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 three sentences, with the action presented first. It is direct and contains no filler. Every sentence adds value, making it highly concise and well-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?

Given the tool's simplicity (destructive, 3 params, no output schema), the description covers purpose, bulk support, and a warning. However, it lacks details on return behavior, error handling, or what happens after deletion. It is adequate but not thorough.

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 that 'id' is a UUID and notes that 'ids' enables bulk execution. However, the 'account' parameter is not mentioned. With 0% schema coverage, the description partially compensates for two of three parameters but leaves one 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 'estorna (remove) uma baixa por id', specifying the action (remove) and the resource (settlement by ID). It distinguishes itself from sibling tools like 'contaazul_update_settlement' and 'contaazul_list_settlements' by explicitly being a delete operation.

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

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

The description warns that it is a destructive operation and advises confirmation ('Operação destrutiva, confirme antes'). However, it does not provide explicit when-to-use vs alternatives or when not to use it. The context is clear but lacks 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 non-destructive creation (destructiveHint=false). Description adds the integration date requirement but does not disclose potential side effects like changes to receivable status or return behavior. Some transparency but gaps remain.

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 purpose and essential details. No superfluous text; every part 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?

No output schema, 0% schema coverage, and the description omits details like exact JSON format for 'data', the role of 'account', and return/error behavior. Incomplete for a moderately complex 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%, requiring the description to explain parameters. It explains the structure of 'data' (payment type, reference, optional max parcels) but does not explain the 'account' parameter at all. Partial compensation.

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 generates a charge (boleto, pix, or payment link) from a receivable, listing specific payment types. This distinguishes it from sibling tools like contaazul_receivable_create or contaazul_settle_installment.

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

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

Mentions a requirement (integration after March/2025) and describes the data parameter, but does not explicitly state when to use this tool vs alternatives or when not to use it. Usage context is implied but not fully explicit.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds that the tool accepts batched execution via the 'ids' parameter, which is useful 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: first covers purpose and id source, second covers batch support. No filler or redundancy. Front-loaded and 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?

Tool has 3 parameters, no output schema, but annotations exist. Description explains purpose and batch support, but omits details about the return format and the 'account' parameter. Adequate for a simple getter but lacks 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 coverage is 0% (no descriptions in schema). The description explains the 'id' and 'ids' parameters (the latter for batch), but does not explain the 'account' parameter. This partial explanation is adequate 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?

The description clearly states it retrieves the current balance of a financial account by ID (bank/cash/card), specifies where to get the ID (contaazul_list_financial_accounts), and mentions bulk support. It is distinct from siblings like contaazul_get_initial_balance.

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

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

The description provides clear usage context: use to get current balance, get ID from another tool, and supports batched execution. However, it does not explicitly state when not to use it or mention alternatives like contaazul_get_initial_balance for initial balances.

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 behavior. The description adds context about batch execution and the returned data structure (items, client, value composition), which enhances transparency without contradicting 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: first states core purpose with return fields, second adds bulk support. No wasted 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?

No output schema, but the description outlines the main return components (items, client, value composition). It covers the tool's role among siblings (get detail vs list/create/delete). Could be slightly more specific about output fields, but adequate for a retrieval 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 has 3 parameters (id, ids, account) with 0% description coverage in schema. The description explains 'id' and 'ids' for single and batch retrieval, but completely ignores 'account', leaving its purpose unclear. This is a significant 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 the tool gets budget details by id, listing the returned fields (itens, cliente, composição de valor) and mentioning bulk support. This distinguishes it from listing tools like contaazul_list_budgets.

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 via the 'ids' parameter, guiding batch usage. However, it does not specify when not to use this tool or compare to alternatives beyond implicit distinction from 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. The description adds minimal value by mentioning the returned fields but does not disclose error handling, rate limits, or required authentication beyond what annotations imply. It provides some context but not 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 a single sentence in Portuguese that is direct and to the point. It is concise with no unnecessary information. However, for non-Portuguese agents, the language might reduce clarity, but conciseness is maintained.

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

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

Given the absence of an output schema, the description partially explains the return value with example fields. However, it does not specify the complete output structure, potential errors, or how the 'account' parameter affects results. It is adequate for a simple getter but lacks full completeness.

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

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

The schema has one parameter 'account' with no description, and the description does not explain its purpose or expected format. With 0% schema description coverage, the description should compensate but fails to clarify what 'account' refers to (e.g., ID, email, or slug).

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 specifies the tool returns company data (CNPJ, corporate name, tax regime). It clearly identifies the resource and provides specific fields, distinguishing it from sibling tools like 'get_person' or 'get_sale'. However, it does not explicitly state that it retrieves data for the currently authenticated company, which could cause ambiguity.

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

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

No guidance is provided on when to use this tool versus alternatives or any prerequisites. The description lacks context about authentication or the need for an active Conta Azul company. Sibling tools exist, but no differentiation or usage conditions are given.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds bulk execution support, but no additional behavioral context like auth requirements, rate limits, or response structure. Within annotations' context, the description provides moderate added 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?

Two sentences, front-loaded with core purpose. Efficient and no fluff. 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?

Despite annotations and simple schema, description lacks return value information (no output schema) and does not detail parameter semantics. For a read operation with 3 params and no output schema, more details (e.g., response fields, pagination) are needed for 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 description must compensate. Only 'ids' is loosely explained ('bulk support'); 'id' and 'account' are undocumented. This does not adequately clarify parameter usage or constraints.

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 contract details by ID, listing specific fields (client, terms, payment condition, value composition). Distinguishes from sibling tools like contaazul_list_contracts which list contracts without 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?

Implies use when you need a single contract's details or batch by IDs, but no explicit guidance on when not to use or alternatives. Sibling tools exist for other entities but no comparison 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 declare readOnlyHint=true and idempotentHint=true, which already indicate safety. The description adds that date parameters are normalized and omission uses a wide window. However, it does not explain what 'initial balance' means or if there are pagination 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?

Two sentences: one for purpose, one for parameter details. No wasted words; front-loaded with the core action. 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?

The tool has no output schema and 3 parameters with one undocumented. The description covers the date parameters well but omits return format and the account parameter. For a simple read tool, it is adequate but missing details for full autonomous 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 description coverage is 0%, so the description must compensate. It explains data_inicio and data_fim formats and default behavior but leaves the 'account' parameter undocumented. Partial compensation for two of three 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 retrieves initial balances of financial accounts by period. The name and sentence together make the purpose specific, but it does not differentiate from the sibling tool 'contaazul_get_account_balance' which could be confused.

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_get_account_balance' or 'contaazul_list_accounts'. It mentions parameter omission behavior but lacks context for 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?

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the agent knows the operation is safe and idempotent. The description adds the batched execution behavior, which is value beyond annotations. However, it does not disclose response format or error handling, which would be expected given no output schema.

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

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

The description is extremely concise with two short sentences. The first sentence front-loads the primary purpose, and the second adds the bulk feature. No superfluous text.

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

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

Despite being a simple read tool with good annotations, the description lacks details on response, error cases, and the 'account' parameter. The batch support is mentioned but not explained in terms of constraints or behavior. Overall, it feels incomplete for a tool with no output schema and undocumented 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?

With 0% schema description coverage, the description must explain parameters. It mentions 'id' in the first sentence and hints at 'ids' for batch, but fails to explain the optional 'account' parameter. The agent lacks information to correctly use that 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 parcela por id' which specifies the action (get detail) and resource (installment by id). However, it does not distinguish from the sibling tool 'contaazul_list_installments', so the agent needs to infer when to use this get tool versus listing.

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: accepts ids for batched execution', which gives context on batch usage. However, it provides no guidance on when to use this tool instead of alternatives (e.g., list_installments) or any prerequisites. The usage is implied but not explicit.

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

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

Annotations already declare readOnly, idempotent, not destructive. Description adds bulk support but no additional behavioral context like auth needs or return details.

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

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

Two concise sentences deliver purpose and bulk capability with no unnecessary words.

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

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

For a simple get operation with annotations covering safety, the description is fairly complete, but missing parameter detail for 'account' 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 coverage is 0%, description partially explains id and ids (bulk) but does not explain the 'account' parameter, leaving 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?

Clearly states it gets details of an NF-e by id, and mentions bulk support. This distinguishes it from list tools like contaazul_list_invoices_nfe.

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?

Indicates batch execution via ids parameter, but does not explicitly state when not to use or provide alternatives. Context is clear but lacks 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=true, destructiveHint=false, and idempotentHint=true, so the agent knows it is a safe read operation. The description adds the behavioral trait of bulk support via 'ids' parameter, which provides additional 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?

The description is extremely concise with two short sentences. The first sentence states the core purpose, and the second adds the bulk support capability. There is no fluff or redundancy.

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

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

Given the tool is simple (3 parameters, no output schema, read-only annotations), the description covers the main functionality and bulk support. However, it fails to explain the 'account' parameter and does not describe return values, leaving some 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 input schema has 0% description coverage, so the description must compensate. It explains 'id' and 'ids' by mentioning 'by id' and 'bulk support', but the 'account' parameter is not mentioned at all, leaving its purpose 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 'Detalhe de uma pessoa por id' (detail of a person by id), specifying the verb and resource. The mention of bulk support further clarifies its capability, and it is clearly distinct from sibling tools like '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?

The description does not explicitly state when to use this tool versus alternatives such as 'contaazul_list_people'. It implies usage for fetching details by id, but lacks guidance on when not to use it or comparison with siblings.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, making the tool's safe nature clear. The description adds the behavioral trait of bulk execution via the 'ids' parameter, which is positive but not comprehensive. 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?

Two sentences with no fluff. The first sentence directly states the core purpose, and the second adds a key usage note. Highly efficient and 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?

The tool is simple, but without an output schema, the description omits any detail about the return structure. For a 'get' tool, this is acceptable but leaves the agent without clarity on the response format. Complete enough for basic invocation 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 the description must compensate. It adds meaning for 'id' (implicitly) and 'ids' (bulk support), but does not address the 'account' parameter. Partial improvement over the schema, 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?

The description 'Detalhe de uma venda por id' clearly states the function is to retrieve details of a specific sale by its ID. This distinguishes it from sibling tools like 'contaazul_list_sales' that list multiple sales, and other get tools that focus on different entities.

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

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

The description implies usage when you have a sale ID, but does not explicitly state when to use this tool versus alternatives like 'contaazul_list_sales'. The bulk support note provides some usage context but no clear when-not or 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds bulk execution context, which is a behavioral trait beyond annotations. No contradictory information.

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 purpose. Every word is meaningful; no redundancy or unnecessary detail.

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

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

For a simple get-by-ID tool with no output schema, the description covers the core functionality and bulk option. But it omits any mention of return format or data fields, and lacks explanation of what a 'baixa' entails.

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 explains the 'id' parameter as UUID and mentions 'ids' for bulk. However, the 'account' parameter is left unexplained, leaving 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?

Clearly states the tool retrieves details of a settlement by ID. The description explicitly mentions single ID and bulk support via 'ids', distinguishing it from sibling tools like 'contaazul_list_settlements' which list settlements.

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, such as listing all settlements first. Mentions bulk support but no explicit when-not or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds minimal behavioral context. It mentions the tool returns company_id and label, which is useful but not extensive.

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

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

The description is a single concise sentence that front-loads the verb and resource. 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?

The description provides expected output fields but omits explanation of the parameter, pagination, or sorting. Given no output schema, it partially compensates but leaves 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?

With 0% schema description coverage, the description does not explain the single optional 'account' parameter. This is a significant gap as the agent cannot understand how to use it.

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 Conta Azul companies linked to the install, and specifies the output includes company_id and label. It distinguishes from sibling list_* tools which list other entities.

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

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

No explicit guidance on when to use or avoid this tool compared to alternatives. It implies use for listing companies, but does not mention exclusions or prerequisites.

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

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

Annotations provide readOnlyHint, idempotentHint, and destructiveHint, but the description adds the behavioral detail of pagination (Paginado) and the specific fields returned. This goes beyond annotations, though it lacks details on sorting or filtering.

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

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

The description is extremely concise—two short phrases in Portuguese—front-loading the purpose and key information (fields, pagination). 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 list tool with no output schema and 0% parameter descriptions, the description is incomplete. It mentions fields and pagination but omits input parameter explanations and does not clarify the return structure (e.g., that it returns a list of budgets). The agent lacks critical information to invoke the tool correctly.

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

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

Schema description coverage is 0%, and the tool description does not explain the three parameters (pagina, account, tamanho_pagina). The description only covers output fields, leaving parameter semantics entirely to the schema, which provides no 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 explicitly states it lists budgets and specifies the fields returned (client, number, total, situation, version), with 'Paginado' indicating pagination. This clearly identifies the verb (list) and resource (budgets), distinguishing it from sibling list tools for other entities.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives. While the name and sibling context imply it is for budget listing, there is no mention of use cases, exclusions, or comparisons to other list tools, leaving the agent to infer 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds no extra behavioral context beyond the tool's purpose.

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 lacking necessary detail. It earns its place but could be more substantive.

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

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

With 4 undocumented parameters and no output schema, the description is far from complete. It does not address pagination, filtering, or the meaning of DRE for non-Portuguese speakers.

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%, and the description provides no explanation of parameters like 'tipo', 'pagina', 'account', or 'tamanho_pagina'. The agent has no guidance on parameter usage.

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 financial categories (DRE), specifying the verb and resource. However, it does not differentiate from sibling tools like contaazul_list_accounts or contaazul_list_cost_centers, which might 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?

No guidance on when to use this tool vs alternatives. Among many similar list tools, there is no context for 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?

Annotations already declare readOnly, idempotent, non-destructive. Description adds that only IDs are returned, paginated, and requires a date range. 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?

Short, front-loaded with purpose, then key parameters and behavior. No fluff. Missing parameter docs but still concise.

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?

Explains core functionality and two parameters. Could add brief descriptions for pagination parameters and account. No output schema, so return value is implied but not fully 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 description coverage is 0%. Description adds meaning for 'data_inicio' and 'data_fim' (date format) but ignores 'pagina', 'account', and 'tamanho_pagina'. For a tool with 5 undocumented params, the description should explain more.

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 lists IDs of changed financial events in a period for incremental sync/reconciliation. Distinguishes from sibling tools like 'contaazul_get_installment' and other list tools by focusing on changed events.

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 usage for incremental sync/reconciliation and directs to use 'contaazul_get_installment' for details. Could be improved by noting when not to use (e.g., if you need full 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?

Discloses API limitations (no GET by id, no cancel/delete) and bulk execution support. This adds value beyond annotations which already mark it as read-only and idempotent. 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?

Highly concise, with key information front-loaded. Every sentence adds value without redundancy.

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

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

Lacks description of output format/fields, which is important given no output schema. Covers filtering and limitations well, but does not describe pagination response or error handling.

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 meaning to most parameters: date format for data_inicio/data_fim, pagination limits, and the role of cliente_ids for batching. However, the 'account' parameter is not described, and there is no explanation of return value 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?

Description clearly states 'Lista contratos' with specific filtering criteria (date interval, pagination, client ID, text search) and bulk support. It implicitly distinguishes from sibling tools like get_contract (single contract) and delete_contract.

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 context on date parameter defaults (wide window if omitted) and pagination max size (50). Mentions bulk cliente_ids for batched execution. Does not explicitly contrast with get_contract or other list tools, but the sibling names are distinct 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds no behavioral context beyond that, such as pagination behavior, data scope, or any side effects.

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

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

The description is a single sentence with no wasted words, but it is overly minimal. Conciseness is achieved at the expense of completeness.

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, no parameter explanations, and no usage guidance, the description is highly incomplete for a list tool with three parameters. An agent cannot properly utilize this tool without additional information.

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 does not explain any of the three parameters (pagina, account, tamanho_pagina). Their Portuguese names are not clarified, leaving ambiguity for an agent.

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). It is straightforward but does not differentiate from sibling list tools, though the resource name 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 guidelines on when to use this tool versus alternatives (e.g., other list tools). No exclusions or context for when not to use it.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description carries less burden. However, it adds no extra behavioral details (e.g., pagination behavior, effect of filters), missing an opportunity to enhance transparency.

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 with no redundant information, achieving conciseness. However, it may be too brief given the lack of parameter documentation.

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 0% schema coverage and no output schema, the description fails to provide sufficient context for proper tool usage, omitting details on filtering, pagination, and return 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 description coverage is 0%, yet the description does not explain the purpose of any of the three parameters ('pagina', 'account', 'tamanho_pagina'). Without clarification, agents must infer meaning from parameter names alone.

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 (list) and the resource (financial accounts) with subtypes (bank, cash, card), providing a specific verb+resource identification that distinguishes it from sibling tools like 'contaazul_list_accounts'.

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

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

No guidance on when to use compared to similar list tools; no explicit context or alternatives provided. The description only states what it does without usage direction.

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

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

Annotations already cover safety (read-only, idempotent, non-destructive). The description adds context about the API limitation (no flat listing) and the scoping to one event, which is useful. 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 with front-loaded purpose and a clear alternative. Every word earns its place, no redundancy.

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

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

Given 0% parameter descriptions and no output schema, the description is adequate for core purpose but lacks details on return format, pagination, or optional parameter behavior. Could be more complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains id_evento but not the optional account parameter. Partial coverage leaves 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 installments for one financial event, specifying the required parameter. It distinguishes itself from sibling tools like list_receivables and list_payables, which are for scanning all receivables/payables.

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 (for a single event) and when not to, offering alternative tools for broader scans. This provides clear guidance 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool supports filters (date range, status, pagination) but does not disclose how pagination works, default page sizes, ordering, or limits. No additional behavioral traits beyond annotations are revealed.

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 the tool's purpose and available filters. It is front-loaded and to the point. However, the omission of the 'account' parameter is a minor flaw, but overall conciseness is strong.

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

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

Given the absence of an output schema, the description should explain the return structure or pagination behavior. It does not. It also fails to mention that the tool returns a paginated list, what the default page size is, or how to handle the 'account' parameter. The description is incomplete for effective 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 description coverage is 0%, so the description must compensate. It lists 5 of the 6 parameters (missing 'account') and provides minimal semantics by naming the filters (e.g., 'tamanho_pagina' as page size). However, it does not specify data formats for dates, possible values for status, or the meaning of 'account'. The omission of one parameter reduces completeness.

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 fiscal notes (NF-e), which is a specific resource type. It implicitly distinguishes from siblings like 'contaazul_get_invoice_nfe' and 'contaazul_list_invoices_nfse' by using the term 'NF-e', but does not explicitly differentiate. The verb 'Lista' (lists) is precise.

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 that 'contaazul_get_invoice_nfe' is for a single invoice or that 'contaazul_list_invoices_nfse' lists a different type. The context of usage is only implied by the tool name and filter 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 indicate readOnlyHint=true and idempotentHint=true, which the description aligns with. The description adds behavioral details like the 15-day window and default date behavior, which go 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 sentences deliver the essential purpose, constraints, and filter options without waste. Information is front-loaded and easy to parse.

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

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

For a list tool with 13 parameters and no output schema, the description covers the critical filters and constraints. It does not explain pagination or return format, but those are standard; still, a bit more detail on pagination behavior would 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?

The input schema has 13 parameters with no descriptions (0% coverage). The description explicitly explains 10 of them, including required dates, status enums, and negotiation types, adding significant meaning beyond the 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?

The description clearly states the tool lists NFS-e (service invoices) with filtering, and the name distinguishes it from related list tools like contaazul_list_invoices_nfe. The purpose is specific and actionable.

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 required parameters (data_competencia_de, data_competencia_ate) with format and maximum date range, plus lists optional filters. It does not explicitly compare to alternatives, but the tool's domain is clear from the name and context.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, indicating safe read operation. The description adds filter details but no additional behavioral context beyond what annotations imply.

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

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

Two concise sentences: first states purpose, second lists filters. Front-loaded with key information, no superfluous 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?

Despite annotations, the description lacks return value info, default pagination, ordering, and examples. Missing parameter 'account' explanation. For a list tool with 6 parameters and no output schema, more detail is needed.

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 five of six parameters (pagina, tamanho_pagina, data_vencimento_de, data_vencimento_ate, status) with formats and enum values, but misses the 'account' parameter. Explanations are minimal and add limited semantics beyond parameter names.

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

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

The description clearly states 'Lista contas a pagar (parcelas de despesa)' identifying the resource as payables/expense installments. It distinguishes from sibling tools like 'contaazul_list_receivables' by specifying payables versus receivables.

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 filter parameters but does not provide explicit guidance on when to use this tool versus alternatives. No mention of when not to use or comparison with similar list tools like 'contaazul_list_installments'.

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, making the tool safe. The description adds filter details but does not contradict annotations. No additional behavioral traits (e.g., rate limits, pagination limits) are disclosed.

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

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

The description is concise (two sentences) and front-loaded with the main purpose. Every sentence adds value, but it could be slightly more structured (e.g., separando função e filtros).

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 six parameters (zero required) and no output schema, the description covers the basic purpose and filter options but lacks details on the return structure, pagination behavior, or the purpose of the 'account' parameter. It is adequate but incomplete for complex 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 partly compensates by listing five parameters (tamanho_pagina, pagina, busca, tipo_perfil, ativo) and explaining 'busca' as search by name/document. However, it omits the 'account' parameter and does not detail value formats or enums.

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 people (clientes, fornecedores, vendedores, transportadores) with a specific verb 'Lista'. It distinguishes from sibling tools like 'contaazul_get_person' by the plural resource, but does not explicitly differentiate from other list 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?

The description mentions available filters via params, implying usage context for retrieving people with criteria. However, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., single retrieval vs. list), nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds filter context but no further behavioral details such as pagination behavior 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?

Very short and front-loaded with the purpose and filters. No extraneous text, but could include more detail without sacrificing conciseness.

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

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

For a tool with 5 parameters and no output schema, the description is incomplete. It lacks explanation of response format, pagination details, and the 'account' parameter purpose.

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 four of five parameters but does not explain their meanings beyond their names. It omits 'account' parameter. Schema coverage is 0%, and description fails to compensate with semantic detail.

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 registered products, with a specific verb (list) and resource (products). It distinguishes from sibling list tools targeting different entities.

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

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

The description implies usage for listing products but provides no explicit guidance on when to use vs alternatives or when not to use. 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 declare readOnlyHint=true and idempotentHint=true, so the description's safety profile is covered. The description adds filtering details (date range, status, client IDs) but does not disclose pagination behavior or other traits beyond filtering.

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 listing filters. No wasted words, and the structure is front-loaded with the core purpose. Every element serves a 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?

Given 7 parameters with no output schema, the description covers most filtering options but lacks pagination behavior explanation. It is largely complete for a list tool but could be improved with pagination details.

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 6 out of 7 parameters (date format, status enum values, UUID hint). However, it omits the 'account' parameter entirely, which is 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 the tool lists 'contas a receber' (receivables), which is a specific resource. The verb 'Lista' and resource are explicit, and it distinguishes from sibling list tools (e.g., payables) by naming the specific type.

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 (e.g., list_installments). Usage context is implied by the resource name and filters, but no when-not guidance or alternative suggestions 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 and idempotentHint, so safety is clear. The description adds that bulk support via 'cliente_ids' is available, but does not detail behavior such as rate limits, response format, or pagination limits, providing some added value but not deep transparency.

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 short with two sentences, front-loading the purpose. It is concise and efficient, though a more structured list of parameters could improve readability. 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 8 parameters, no output schema, and 0% schema coverage, the description is insufficient. It lacks details on return structure, pagination behavior, error handling, and the 'account' parameter. Significant gaps remain despite annotations covering safety.

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 lists several parameters and notes a date format (YYYY-MM-DD), but does not provide details on value ranges, allowed values for status_venda, or explain the 'account' parameter present in the schema. Parameter semantics are only partially addressed.

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) with a specific verb and resource. It lists relevant filters, distinguishing it from sibling tools like 'contaazul_get_sale' which retrieves a single sale, though it does not explicitly contrast them.

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

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

The description lists available filters and mentions bulk support, guiding basic usage. However, it does not specify when to use this tool over alternatives (e.g., for a single sale use get_sale) or any prerequisites, providing minimal contextual guidance.

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

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

The description adds no behavioral context beyond annotations (readOnlyHint, idempotentHint, destructiveHint). Annotations already indicate it is safe and idempotent, but the description does not elaborate on paging or search behavior.

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

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

The description is extremely concise (one sentence), but it sacrifices completeness. It is front-loaded but lacks substance for a tool with multiple parameters.

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

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

Given four undocumented parameters and no output schema, the description is grossly incomplete. An agent would not know how to form a valid request or interpret the response.

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 4 parameters, and the description does not explain any parameter. This leaves the agent without hints on how to use 'busca', 'pagina', 'account', or 'tamanho_pagina'.

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 'Lists registered services' clearly states the action and resource, matching the tool name. However, it does not differentiate from other list tools in the sibling list, but the resource 'services' 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?

No guidance on when to use this tool versus alternatives like list_products or list_invoices. No context about filtering or pagination 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 indicate readOnlyHint=true and idempotentHint=true, so the description's job is to add value beyond those. It does so by noting bulk execution support. However, it does not disclose rate limits, authentication needs, or return format (since no output schema). The added context is sufficient for a read-only list operation.

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

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

The description is extremely concise: two sentences and a one-line bulk note. It front-loads the main purpose and adds essential detail without redundancy. 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?

For a tool with three parameters and no output schema, the description provides the core purpose, explains the primary parameter, and mentions batch support. Missing explanation of 'account' and return format prevent a perfect score, but the description is still informative enough for an agent to use the tool effectively.

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

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

Schema description coverage is 0%, so the description must add meaning. It explains 'id' as the UUID of the parcel and introduces 'ids' for bulk execution. However, 'account' is not explained at all, leaving a gap. This partial coverage justifies a score of 3.

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

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

The description clearly states the tool lists settlements of an installment, specifying the 'id' parameter as the UUID of the installment. This distinguishes it from sibling tools like 'contaazul_get_settlement' which retrieves a single settlement, and other list tools.

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

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

The description mentions bulk support for batched execution via 'ids', which provides a usage hint. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'contaazul_get_settlement' for a single settlement), nor does it provide exclusion criteria.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context: paginated, date constraints, and default period. No contradictions; adds 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?

Two concise sentences, front-loaded with core action and parameters. Efficient but sacrifices completeness for brevity, missing some parameter details.

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

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

With 5 optional parameters and no output schema, the description is incomplete. It explains date parameters and pagination concept but omits account, page number, and page size details. Agent would lack full context to use tool correctly.

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

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

Schema description coverage is 0%, so the description must explain parameters. Only data_inicio and data_fim are explained with format and default. pagina, account, and tamanho_pagina are not described, leaving critical semantics 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 transfers between financial accounts by period, which is specific and distinguishes it from sibling list tools (e.g., accounts, budgets). The purpose is unambiguous.

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

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

The description provides clear usage context: use for reconciliation, specify date range with a 1-year max window, default to last 365 days. It doesn't explicitly compare to alternatives but the context is sufficient for correct invocation.

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

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

The description adds value beyond annotations by disclosing asynchronous behavior (returns 202), the exact enum for payment methods, and normalization of short forms. However, it does not cover error conditions or required permissions.

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 covering purpose and details, but could benefit from better structure (e.g., separating parameter description from behavior).

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 clarifies the async return. It covers main input and behavior, but misses the 'account' parameter and assumes knowledge of another tool's 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?

With 0% schema description coverage, the description compensates by detailing the structure of the 'data' parameter (listing fields and enum values), but completely omits the 'account' parameter, leaving its meaning 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 the verb 'Cria' (creates) and the resource 'evento financeiro de conta a pagar' (payable financial event), and distinguishes it from the sibling 'contaazul_receivable_create' by noting the same structure but for payables.

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 creating payable events and references the structure of 'contaazul_receivable_create' for similarity, but does not explicitly state when to use this tool versus alternatives like 'contaazul_settle_installment' or when not to use it.

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

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

Annotations already set destructiveHint=true, so the description reinforces this and adds 'confirme antes' as a behavioral guideline. It also reveals bulk capability beyond what annotations provide. 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?

Two concise sentences: first states purpose and warning, second adds bulk support. Front-loaded and 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?

For a simple deletion tool with destructiveHint annotation and no output schema, the description covers core purpose, destructive nature, and batch capability. Could mention post-deletion behavior but not essential.

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 by explaining use of 'id' for single removal and 'ids' for batch execution. The 'account' parameter remains undocumented, but two of three parameters are clarified.

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

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

The description explicitly states the verb 'Remove' and the resource 'pessoa por id', clearly indicating a deletion operation. This distinguishes it from sibling tools like 'contaazul_get_person' (read) and 'contaazul_person_write_create' (create).

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 a clear warning 'Operação destrutiva — confirme antes' (destructive operation, confirm before) guiding cautious use. Also mentions bulk support with 'ids'. However, it does not explicitly state when not to use it or compare to alternatives among siblings.

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

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

The description discloses key behavioral traits beyond annotations: partial merge on update, validation of the entire record by Conta Azul, and bulk support. Annotations only provide basic hints, so the description adds significant 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 front-loaded with the purpose but is somewhat verbose with mixed details for create and update. It could be more structured (e.g., separated sections) without losing 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?

While the description covers the core operation and validation behavior, it omits mention of return values (e.g., created/updated person ID). For a write tool with no output schema, this is a notable gap that 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?

With 0% schema description coverage, the description partially compensates by detailing the 'data' parameter structure, including enums for 'tipo_pessoa' and 'perfis'. However, it does not explain 'id', 'ids', or 'account' parameters, 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 that the tool creates or updates a person, with specific required fields for each action. It distinguishes itself from sibling tools like 'contaazul_person_delete' and 'contaazul_person_write_update' by covering both operations in one 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 provides explicit guidance on when to use 'action=create' versus 'action=update', including required fields. However, it does not clarify how this tool relates to the sibling 'contaazul_person_write_update', which might cause confusion about which to use.

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. The description expands on this by detailing partial update behavior (merge, null clears), validation on entire record, and bulk execution. It does not disclose potential side effects like overwriting existing data, but the merge behavior is well explained.

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 structured with clear sections for create, update, enums, and bulk support. It is front-loaded with the main purpose. Slightly verbose but each sentence adds necessary detail. Could be slightly more concise by grouping related 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 no output schema, the description does not mention return values or response format. It covers input behavior comprehensively but lacks information on what the tool returns after execution. Also, the `account` parameter is undocumented. For a complex write tool, some output info would be helpful.

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 significant meaning to `data` (JSON with required/enum fields), `id` (for update), and `ids` (for bulk). However, the `account` parameter is not explained at all, 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 creates or updates a person, specifying required fields for each action (create: nome, tipo_pessoa, cpf/cnpj; update: id and changes). It distinguishes from sibling tools like contaazul_person_write_create and contaazul_person_delete by covering both create and update in one tool, and mentions bulk support.

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 internal guidelines: for create, require specific fields via data; for update, require id and only changed fields. Warns about validation on update requiring missing fields. However, it does not explicitly differentiate from the sibling tool contaazul_person_write_create, which may cause confusion about which tool to use for create 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 indicate readOnlyHint=false and destructiveHint=false, but the description adds critical context: the Conta Azul API v2 does not expose update or GET-by-ID for products. This clarifies that creation is the only write operation and that products cannot be individually retrieved later. 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 extremely concise with only two sentences. The first sentence directly states purpose and required fields. The second sentence adds essential contextual information about API limitations and a sibling alternative. 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?

Given the tool's simplicity, lack of output schema, and annotations, the description covers: purpose, required fields, API limitations, and an alternative tool. It is mostly complete but could mention the response format (e.g., whether it returns an ID) or potential errors.

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

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

With 0% schema description coverage, the description compensates by explaining that the 'data' parameter must be a JSON containing 'nome' and 'valor_venda' as required fields. This adds semantic meaning beyond the schema's simple 'string' type. However, the 'account' parameter is not explained.

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 a product and specifies required fields ('nome' and 'valor_venda') in the 'data' JSON. It also distinguishes itself from sibling tools by noting that the API lacks update and get-by-ID endpoints, directing users to 'contaazul_list_products' for queries.

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 tells when to use this tool (to create a product) and when not to (for updates or retrieval, as the API doesn't support them). It provides a clear alternative: use 'contaazul_list_products' with filters for querying products.

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=false, etc.), the description explains that the tool is a creator (mutation), returns 202 with protocolId and status, and is asynchronous. 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 verbose but efficiently structured, front-loading the purpose and then detailing fields. Every part adds value, though slightly long.

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 complexity (many nested fields, enums, references to other tools) and lack of output schema, the description is complete enough, covering return value and dependencies.

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 compensates fully by explaining the 'data' parameter as a JSON with detailed required and optional fields, formats, and enums, adding 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 evento financeiro de conta a receber' (creates a financial event of accounts receivable), specifying the verb and resource. It differentiates from siblings like 'contaazul_payable_create' by the resource type, though not explicitly naming alternatives.

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

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

The description provides detailed required and optional fields, including references to other tools for obtaining UUIDs, but does not explicitly state when to use this tool vs alternatives or when not to use it.

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

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

Description adds context beyond annotations: reinforces destructive operation with a confirmation warning and highlights bulk execution via 'ids'. 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 short sentences, front-loaded with purpose, no filler. Every word contributes meaning.

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 simple mutation, description covers destructive nature, confirmation need, and bulk capability. Could mention return behavior or prerequisites, but 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?

Adds meaning to 'ids' parameter via 'Bulk support: accepts ids'. However, 'id' and 'account' parameters have no description, and schema coverage is 0%, so description only 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 it cancels a sale ('Cancela uma venda'), using a specific verb and resource, effectively distinguishing it from related tools like get_sale or write_create.

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 to confirm before use ('confirme antes') due to destructive nature, and mentions bulk support. Lacks direct comparison to alternatives, but the warning is valuable.

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 reveals endpoints for create and update, and that it accepts bulk ids. Annotations are all false, so no inherent behavioral hints. It lacks details on destructive effects, authentication, or error scenarios.

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 concise but mixes Portuguese and English, and includes an internal note '[Flattened action: create]' that may confuse. It could be streamlined.

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 it is a mutation tool with no output schema and 0% schema coverage, the description lacks details on return values, error handling, and the exact effect of create vs update. It also fails to clarify the relationship with the update sibling 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 the description must compensate. It explains 'data' as the full JSON payload and implies 'id' is for updates. However, 'account' is not explained, leaving part of the parameter set 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 creates or updates a sale, distinguishing between action=create and action=update. However, it does not explicitly differentiate from the sibling tool 'contaazul_sale_write_update', which likely focuses on updates only.

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 provides context on when to use create vs update based on the action parameter and mentions bulk support. However, it offers no guidance on when to avoid this tool or prerequisites, and does not contrast with the update-only sibling.

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 a write operation (readOnlyHint=false) but no destructive behavior (destructiveHint=false). The description adds bulk support via 'ids' and endpoint details, but lacks information on side effects, concurrency, or required permissions.

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 short and includes the essential purpose and parameter info. The internal note '[Flattened action: update]' adds slight clutter but does not severely impact readability.

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 0% schema description coverage and no output schema, the description lacks crucial details such as error handling, prerequisites, return values, and when to use this tool over the sibling 'contaazul_sale_write_create'. The ambiguity between create and update 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?

The description explains the 'data' parameter as the complete sale payload in JSON and mentions bulk support for 'ids'. However, 'id' and 'account' are not explained, and the relationship between 'id' and 'ids' is unclear. The create vs. update logic is 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 creates or updates a sale, specifying endpoints for each action. However, it does not differentiate from the sibling tool 'contaazul_sale_write_create', 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?

No explicit guidance is provided on when to use this tool vs. alternatives like 'contaazul_sale_write_create' or 'contaazul_sale_cancel'. The mention of bulk support is helpful but not 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 adds minimal behavioral context beyond the annotations. While annotations indicate it is not read-only and not destructive, the description only confirms creation without discussing side effects, authorization needs, or data impact.

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-loads the purpose. However, it lacks structure and could include more details without becoming verbose. It is minimal but not optimally 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?

Given there is no output schema and only vague parameter hints, the description fails to provide a complete picture. It does not explain return values, error conditions, or required validation, leaving gaps for effective invocation.

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 only vaguely explains the 'data' parameter as 'JSON com nome, valor, etc.' and omits the 'account' parameter entirely. This is insufficient for correct parameter use.

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 a service ('Cria um serviço'). The verb and resource are specific. However, it does not distinguish from sibling write tools like 'contaazul_product_write' or 'contaazul_contract_write', lacking differentiation.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or conditions. The agent is left to infer usage from the name alone.

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

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

The description adds behavioral context beyond annotations: it notes concurrency control (`versao` auto-fetched), bulk support, and a warning about incorrect payment method causing a 400 error. However, it does not disclose side effects like marking the installment as settled or possible failure modes.

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

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

The description is reasonably concise for the amount of information provided. It is structured with purpose first, then parameter explanations, and finally bulk support. It is not overly verbose, though some details could be reorganized.

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 complexity (4 parameters, no output schema, no annotations), the description covers the main aspects: required fields, enum values, error conditions, and bulk execution. However, it omits the `account` parameter and does not explain return value details or error handling beyond the specific 400 error.

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 `id` and `data` parameters in detail, including the full list of allowed payment method enums. However, the `ids` parameter is only briefly mentioned for bulk support, and the `account` parameter is not described at all. This leaves a gap for two of four 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 it registers the receipt/payment of an installment. It uses a specific verb ('Registra a baixa') and resource ('parcela'), distinguishing it from siblings like 'update_settlement' and 'delete_settlement'. However, it could be more explicit that it creates a settlement record.

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

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

The description does not guide when to use this tool versus alternatives. It mentions that the `id` comes from list/get installment tools, implying prerequisites, but provides no explicit when-not or comparison to related tools like 'update_settlement' or 'delete_settlement'.

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. The description adds value by noting the operation is sensitive and requires confirmation, and by mentioning bulk support. It does not disclose further behavioral traits like reversibility or required permissions.

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. The first states the core action and sensitivity, the second adds bulk support. No wasted words; information is front-loaded and structured effectively.

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 3 parameters and no output schema, the description covers the action, sensitivity, and bulk capability. However, it omits any details about return values, side effects, or reversibility, leaving some context 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 schema has 0% description coverage for parameters. The description explains 'id' and 'ids' (bulk support) but leaves the 'account' parameter undocumented. This 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 encerra um contrato (terminates a contract) by id, with bulk support. It distinguishes from sibling tools like get/list contracts, but does not explicitly differentiate from the similar 'contaazul_delete_contract', causing slight ambiguity.

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

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 requires confirmation before use, which provides basic usage guidance. However, it does not specify when to use this tool over alternatives like delete_contract, nor does it define prerequisites or postconditions.

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

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

The description discloses that the tool uses PATCH (partial update) and that the version field for concurrency control is automatically fetched, so it need not be provided. It also notes bulk support. While annotations are neutral, the description adds useful behavioral context beyond structured fields, though it omits details like error handling or immediate visibility of updates.

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 and well-structured: it starts with the core action and method, lists editable fields, then provides usage alternatives and bulk support. Every sentence adds value, and there is no extraneous text.

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

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

Given the absence of an output schema and the tool's complexity (4 parameters, bulk support, concurrency control), the description covers purpose, usage, alternatives, and key parameter details. It lacks information about return values or error handling, but overall it is sufficiently complete for an AI agent to use the tool correctly.

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

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

With schema description coverage at 0%, the description compensates by explaining the 'data' parameter as a JSON string with specific editable fields and notes that 'versao' is auto-fetched. However, it does not explain the 'id', 'ids', or 'account' parameters, leaving their semantics partially 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 the tool updates fields of an installment using PATCH, lists editable fields, and distinguishes it from sibling tools (contaazul_settle_installment and contaazul_delete_settlement) by naming them explicitly.

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

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

It explicitly states when not to use this tool for payment/settlement or reversal, directing to specific sibling tools. It also mentions bulk support for batched execution, providing clear guidance on 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 not read-only, not idempotent, and not destructive. The description adds that it uses PATCH, that the 'versao' field is fetched automatically, and that bulk execution is possible. However, it does not disclose request/response details, error handling, or permissions.

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

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

The description is concise with two sentences covering the main action and bulk support. It is front-loaded but slightly dense; could be structured into clearer sections.

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 does not mention return values. The 'account' parameter is unexplained. While purpose is clear, the description lacks completeness for a tool with 4 parameters and no 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 description coverage, the description explains 'id' as UUID and 'data' as JSON with fields like payment_date and payment_method enum. It also mentions 'versao' auto-fetch. However, the 'account' parameter is not explained, leaving a gap despite partial compensation.

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 'Updates a settlement (PATCH)' and specifies that id is the UUID of the settlement, distinguishing it from sibling tools like 'contaazul_settle_installment' (creates settlement) and 'contaazul_delete_settlement' (deletes). It also mentions bulk support, further clarifying 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 provides clear context for when to use this tool (to update a settlement) and mentions bulk support. However, it does not explicitly state when not to use it or provide alternatives like creating or deleting settlements, though this can be inferred from sibling tool names.

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 key behaviors: invoke works even if MCP not installed, returns connect link if credentials needed, returns checkout link if wallet empty, and does not bloat the toolkit. Annotations indicate not read-only and not idempotent, which aligns with the described mutation 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 dense but well-organized, front-loading the purpose and flow. However, it is a single paragraph of text and could benefit from structured formatting (e.g., bullet points) to improve readability for an AI agent.

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 complexity (15 parameters, no output schema, low schema coverage), the description covers the essential workflow, edge cases (credential/payment handling), and action semantics. It provides sufficient context for an agent to correctly select and invoke 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?

Schema coverage is 0%, so the description must compensate. It explains the 'action' parameter and its enum values (search, describe, install, invoke, etc.) and implies the use of 'tool_id' and 'arguments'. However, many parameters (limit, query, mcp_id, message, immediate, etc.) lack specific documentation, leaving the agent to infer from context.

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 for MCPs and tools, stating it is used to search, describe, invoke, install, etc. It distinguishes from sibling tools (e.g., specific integrations like contaazul_*) by being the central catalog and execution mechanism.

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?

Explicit guidance is given: 'use THIS tool FIRST' before any external registry, and the core flow (search → describe → invoke) is outlined. It specifies when to use invoke (one-off) vs install (permanent), and mentions that writes require workspace owner/admin.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, which are not contradicted by the description. The description adds that the tool is for reporting feedback, implying a non-destructive action. It does not disclose backend behavior (e.g., ticket creation), but annotations already cover idempotency and safety.

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 sentences: the first states the purpose, and the second provides key guidance. There is no redundant information, and every word is useful.

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

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

For a simple tool with 3 parameters, the description covers the core purpose and one parameter's usage. However, it omits explanation of the 'message' and 'context' parameters, and since there is no output schema, the return value is not hinted at. It 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?

Schema description coverage is 0%, so the description must compensate. It only partially explains the 'conversation' parameter ('Include the conversation array with recent messages for reproduction'), but fails to explain the required 'message' parameter and the optional 'context' parameter. This leaves significant 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's purpose: 'Report a bug, missing feature, or send feedback.' It uses specific verbs and resources, and it distinguishes itself from sibling tools which are primarily business-specific operations (e.g., contaazul_*).

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 to 'Include the conversation array with recent messages for reproduction,' which helps users understand when and how to use the tool. However, it does not explicitly state when not to use this tool versus alternatives, but context makes it 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds no further behavioral context beyond restating the purpose, so it does not enhance transparency 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 a single, efficient sentence that directly conveys the tool's purpose. 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?

Without an output schema, the description should mention what the returned version information includes (e.g., format, components). It does not, leaving the agent uncertain about the result's 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?

There are no parameters, so schema coverage is complete. The description does not add any additional semantics about what version information is returned. Baseline is appropriate.

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

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

The description clearly states it shows current MCP platform and adapter versions, using a specific verb and resource. However, it does not differentiate from sibling tool 'toolkit_info' which may have overlapping functionality.

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

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

No explicit guidance on when to use this tool versus alternatives. The purpose is self-explanatory but lacks context for selection among related tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds specific context about the kind of state returned (MCPs, connection status, catalog counts), which is useful 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?

One sentence that is front-loaded with purpose, no filler, highly concise.

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 zero parameters, good annotations, and no output schema, the description adequately explains the tool's function. It could optionally elaborate on return format, but not necessary.

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 the schema provides full coverage. The description adds no parameter detail, but none is needed. Baseline 4 for zero 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 that the tool returns toolkit state including installed MCPs, connection status, and catalog tool counts. It distinguishes from sibling tools that perform specific operations.

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

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

The description implies use for checking toolkit status but does not explicitly state when to use this versus other tools or provide exclusions.

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