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

Adds real context beyond the annotations: setting a stage here marks it manual and permanently blocks automatic lifecycle rules from moving it, and the call requires the write scope plus people.write. This is exactly the kind of irreversible side effect and auth requirement the agent needs. It does not restate the destructiveHint already present, which is fine.

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?

Two sentences, zero filler, with the mutation scope front-loaded and the side-effect warning immediately after. Every clause carries 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?

Covers the key hazard (manual stage pinning) and auth needs for a destructive, non-idempotent mutation with no output schema. However, with nested objects and 40% schema coverage it leaves open whether tags/CRM replace or merge, and what happens to omitted fields.

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 only 40% across 5 parameters, so the description must compensate more than it does. It names the stage, tags and CRM field groups, but says nothing about the required app/personId identifiers or whether the nested crm object merges with or replaces existing values.

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 a specific verb and resource ('Change a person's lifecycle stage, tags or CRM fields'), so an agent knows exactly what is mutated. It does not name or contrast itself with siblings like get_person or search_people, but the read/write distinction is obvious from the verb.

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?

Usage is only implied: 'Change' signals a mutation and the required write scope hints at preconditions, but there is no explicit when-to-use/when-not or pointer to get_person for reading or search_people for finding the target id. An agent can infer the use case but gets no routing guidance.

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