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

Annotations declare destructiveHint and idempotentHint, and the description adds genuinely new context: unnamed fields are preserved, the updated record is returned, and the call is not retried. It does not cover auth requirements or what happens if an unknown field name is supplied, which is a notable gap for a mutation tool.

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

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

Extremely tight and front-loaded with the WRITE marker and the core semantics. The 'POST /revise' fragment is close to noise for an agent, but the rest of the sentence carries real 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?

There is no output schema, and the description fills that hole by stating it returns the updated record. Combined with the partial-update guarantee and retry policy, an agent has enough to call it correctly, though error behavior for bad field names is unaddressed.

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 100%, with the id pattern and the fields-object key/value conventions fully documented in the schema itself. The description only echoes 'named fields' and adds no format or validation detail beyond that, so the baseline 3 applies.

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?

States the specific verb and resource ('change only the named fields of an existing record') and pins down partial-update semantics, which is what separates it from vtiger_create_record. Naming the vendor 'revise' call and the POST /revise endpoint leaves no ambiguity about the 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 WRITE prefix and 'existing record' wording imply this is the mutation path for records that already exist, but it never explicitly says when to prefer it over vtiger_create_record or that field names must be resolved via vtiger_describe_module. No exclusions or prerequisites are stated.

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