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

The annotations indicate destructiveHint=false and readOnlyHint=false, suggesting a write operation. The description adds the 'write, altera dados' tag, which reinforces mutation, but it lacks deeper behavioral details such as whether existing fields are overwritten or merged, if there are any required fields beyond id, or what happens on success/failure. Since annotations already cover the safety profile partially, the description adds minimal value beyond what is already known.

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

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

The description is very short and front-loaded: it immediately states the resource and action, includes the endpoint, and adds a key note about bulk support. Every sentence serves a purpose, and there is no filler. It is appropriately concise for a simple edit tool.

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

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

Given that there are 4 parameters, 0% schema coverage, and no output schema, the description is too sparse. It fails to explain how to construct the request body, the role of the 'account' parameter, or the format of 'ids' for bulk. It also does not mention any required authentication or account context. The complexity is moderate, and the description does not provide enough guidance for an agent to use it 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?

The schema has 0% description coverage for parameters, and the description provides no explanation for the properties (e.g., what 'body' should contain, the format of 'ids', or the meaning of 'account'). The description only mentions bulk support with 'ids', which is a small addition, but it does not compensate for the lack of parameter documentation. 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 states the tool edits service invoices ('Editar') and identifies the resource ('Notas Fiscais de Serviços'). It also indicates the specific HTTP method (PUT) and endpoint path, which clearly distinguishes it from sibling list/get/create/delete tools. However, it does not elaborate on what aspects of the invoice can be edited or the data structure, but the core purpose is clear.

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 updating existing service invoices, and the 'write, altera dados' tag indicates mutations. It does not explicitly state when to use this versus other update tools (e.g., notas_fiscais_produtos_update) or provide exclusions, but the resource name and endpoint make the context clear. No explicit user instructions or alternative tools are mentioned.

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