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

Annotations already mark readOnly=false and destructiveHint=true, so the write/mutation profile is known. The description adds valuable non-obvious behavioral context: the evidence-ranking rule, the write-tier approval requirement, and the instruction to treat the approval card as the yes without re-asking. No statement contradicts the annotations.

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 front-loaded with the core operation and scope, then provides selection rules, exclusion, and approval behavior in a compact, bracketed note. Every sentence carries operational value; there is no filler or repetition of schema field definitions.

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 11-parameter mutation tool, the description covers the high-level purpose, input acceptance criteria, exclusions, evidence ranking, and approval workflow; the schema covers parameter semantics. No critical usage gap remains for an agent to call 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?

Schema coverage is 100%, and the schema already defines each parameter, including the class enum and its rank weights. The description mostly recaps the evidence categories rather than adding new parameter-specific meaning, 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?

The description states a specific action and resource: 'Store one piece of REAL Customer Evidence for this company,' and enumerates accepted evidence types. It explicitly distinguishes itself from create_icp by saying it is NOT for inventing personas, so an agent can differentiate it from that sibling.

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 gives explicit when-to-use conditions ('Use when the operator pastes a real customer quote, a call note, a review, or a provenanced usage signal') and an explicit when-not-to-use rule with the alternative ('NOT for inventing personas (use Customer Hunter / create_icp for hypotheses)'). It also instructs the agent on approval handling: call on first clear ask, do not re-ask in chat.

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