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

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description confirms non-destructive behavior. It reveals specific behaviors: save returns id and pdf_url, send makes formulas immediately visible, publish toggles and returns new state, duplicate creates a copy with '(cópia)'. It also mentions skipping blocked formulas with error messages. This adds value beyond annotations, though more detail on error handling for save/publish could improve.

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 organized with a clear list of actions and their details. It front-loads the overall purpose and then uses bullet points for clarity. The 'Flattened action: send' note helps understanding. Some redundancy exists (e.g., explaining publish in both the list and comment), but overall it's well-structured and reasonably 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 the tool's complexity (multiple actions, bulk support, no output schema), the description covers essential behaviors and return values for each action. It mentions bulk execution and excludes deletion. It lacks explicit details on error handling or limits, but these are not critical for basic usage. The description is sufficient for an agent to understand and 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 coverage is 0%, so description carries full burden. It explains key parameters: 'texto' as raw HTML, 'nome' as formula name, 'manipulado_id' for update vs create, and mentions 'patient_ids' and 'manipulado_ids' for bulk. However, parameters like 'account', 'nomes', and default values are not explained. The description adds significant meaning to the most critical params, but somewhat incomplete coverage.

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

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

The description clearly states the tool handles multiple actions (save, send, publish, duplicate) for manipulados, and lists each action's purpose. It distinguishes from the delete sibling tool. However, the name 'write_send' emphasizes 'send' while covering other actions, and sibling tools like webdiet_manipulados_write_publish and webdiet_manipulados_write_duplicate overlap, 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 explains when to use each action: save for create/update, send for copying from banco, publish for toggling visibility, duplicate for copying. It explicitly directs destructive deletes to another tool. However, it does not compare this tool's combined actions against the individual sibling action tools (e.g., when to use this send vs. separate publish/duplicate tools).

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