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

Annotations already provide idempotent=true, destructive=false, and readOnly=false. The description adds useful behavioral context by requiring access to the target contact and the current record revision, implying optimistic concurrency. The security note about CRM field values being untrusted is additional protective context beyond the annotations, and there is 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?

The description is compact: two sentences, with the action and resource front-loaded. The security warning is short and adds relevant context, though it is somewhat generic. It avoids unnecessary detail and stays appropriately sized for the tool's complexity.

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 no description of return values or failure modes. The description also omits what happens on a stale expectedUpdatedAt, how conflicts surface, and what response the agent should expect. Annotations cover idempotency and destructive safety, but the missing output/error behavior leaves meaningful gaps for a mutation 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 description coverage is only 17%, so the description must compensate for undocumented parameters. It loosely maps 'referrer contact' to referrerContactId and 'current record revision' to expectedUpdatedAt, but it never explains idempotencyKey, the conflict semantics of expectedUpdatedAt, or that passing null clears the referrer. This is not enough compensation for the low schema 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 states a specific verb ('Set or clear') and resource ('referrer contact on a lead/deal'), which makes the tool's function immediately clear and distinguishes it from generic alternatives like update_record or set_contact_account. It also implies both the set and clear behaviors, which the title alone does not convey.

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 intended use is implied by the specialized purpose, and the description names required preconditions (access to the target contact and the current record revision). However, it does not explicitly compare with sibling tools, give when-not-to-use guidance, or state alternatives such as using update_record for broader edits.

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