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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description does not need to restate that this is a non-destructive write. It adds one useful behavioral constraint—'for an existing person'—implying person_id must reference an already-created person, but it does not disclose behavior around idempotency, failure modes, or what happens if the person already has a prospect state.

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 a single tight sentence with no filler and the key action front-loaded. It is concise, though brevity comes at the cost of omitting crucial parameter and usage details.

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 a tool with 7 parameters, 0% schema description coverage, no output schema, and no usage guidance, a one-sentence description is grossly insufficient. An agent has no way to understand what 'prospect relationship state' means, how to populate the optional fields, or what a successful response looks like.

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 0%, so the description carries the full burden of explaining the 7 parameters. It explains none of them: person_id is only implicitly referenced, and request_id, source_label, owner_user_id, idempotency_key, last_reviewed_at, and last_contacted_at are entirely unexplained. An agent cannot infer their meaning or formatting from the description.

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 uses a specific verb ('Create') and resource ('Talent CRM prospect relationship state') and scopes it to 'an existing person', which distinguishes it from people_create (which creates a person) and prospects_update (which modifies an existing prospect). The term 'relationship state' is somewhat jargony, but the core action is clear.

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?

No guidance is given on when to use this tool versus alternatives like yardstick_prospects_update, yardstick_prospects_convert_bind, or yardstick_people_create. There is no mention of prerequisites (e.g., the person must already exist) or conditions that would make a different sibling tool more appropriate.

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