Set Main Contact Person

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the schema-side safety profile is covered. The description adds the archiving precondition, which is genuine value, but it omits the key consequence implied by destructiveHint: that the previously designated main contact person is demoted/replaced. With annotations carrying the risk signaling, this is adequate but not complete.

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 short sentences, front-loaded with the action before the constraint. The only waste is the opening line, which merely repeats the tool title verbatim and adds nothing beyond the name.

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 one-parameter mutation with rich annotations and no output schema, the essentials are present: what it does and one blocking precondition. It is still missing what the caller should expect on success (previous main contact's fate) and whether the owning contact is identified from the contact person rather than supplied, which matters given the destructive hint.

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 single parameter is fully documented with format and pattern, so the baseline of 3 applies. The description's phrase 'an existing contact person' adds a small amount of meaning — it must already exist rather than be created — but no new detail about the identifier itself.

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 gives a specific verb and resource ('Makes an existing contact person the main contact person of its owning contact'), which is clearer than the title's restatement. It effectively distinguishes this from the adjacent update_contact_person, but never names that sibling or states the boundary explicitly.

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 supplies one real precondition ('The contact person must belong to a non-archived contact'), which tells the agent when the call will fail. It gives no guidance on when to prefer this over update_contact_person or create_contact_person, nor any note about how to obtain the contact person id — usage is only implied.

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