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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses noteworthy behaviors: 'Replaces stored notes — read first if you need to append', 'Rejects unknown fields', 'Rebuilds life_state so the next get_context_pack inner_circle is fresh', and the auth/cost requirements. This adds real context about side effects and non-obvious overwrite semantics, which is highly valuable for an agent.

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 dense but efficient: it leads with the core mutation, then compactly lists optional fields, key constraints, side effects, auth requirements, and cost. No filler sentences; each clause earns its place. The structure is front-loaded and scannable.

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?

The description covers action, target resource, required parameter, optional field semantics, unknown-field rejection, lifecycle side effects, authentication restrictions, and pricing. An output schema exists, so return-value details are not needed. Nothing essential is missing for an agent to call this 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 100%, so the baseline is 3. The description adds extra semantic value by highlighting the notes replacement behavior, birthday format variants, clearing with null, and the relationship to inner_circle via tier/is_favorite — details that reinforce and expand the schema descriptions without contradicting them.

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 opens with 'MUTATES the authenticated user CRM. Patch one existing person they own (person_id UUID required)' — a specific verb, resource, and scope. It explicitly states it does not create or delete people, which distinguishes it from any create/delete alternatives and clarifies its boundary among sibling tools like update_event and update_food, which target different resources.

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 provides clear context: it patches an existing owned person, rejects unknown fields, and requires API key or OAuth with scope context while share tokens cannot write. It also advises 'read first if you need to append' for notes, which is practical guidance. It does not name sibling alternatives explicitly, but the resource and mutation scope make the intended use clear.

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