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

Beyond the annotations (destructiveHint, idempotentHint, openWorldHint) it discloses that this is a PATCH-style overwrite rather than a full replace, that CPF can be set once but never changed because the vendor rejects it, that health data falls under LGPD, and that reads are cached for 5 minutes. These are exactly the non-obvious behaviors an agent needs before mutating a patient record.

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?

Four short segments, front-loaded with the WRITE marker and the most dangerous constraint (CPF) plus the verification hint. Every sentence carries operational information; nothing is restated from the schema or annotations.

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 an 18-parameter mutation with no output schema, it covers the risky parts (CPF rule, partial overwrite, cache staleness, LGPD sensitivity). Minor gaps remain around error behavior and side effects of fields like price_table_id on billing, which would matter for a destructive write.

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 94%, so parameter meanings are largely carried by the schema and the baseline is 3. The description still adds genuine value the schema lacks: the CPF set-once rule and the partial-update overwrite semantics, which change how the agent should construct its arguments.

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?

Opens with 'WRITE: changes a patient's registration data', a specific verb plus resource, and the CPF-immutability detail plus the pointer to feegow_get_patient makes clear this is a partial update of an existing patient rather than a create. An agent can separate it from feegow_create_patient and feegow_get_patient without opening any schema.

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 states the operating mode (only passed fields are sent and they overwrite stored values) and routes the agent to feegow_get_patient with fresh=true to observe the change, which is concrete usage guidance. It does not explicitly name feegow_create_patient as the alternative for new records, so it falls short of full when/when-not coverage.

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