add_person_channel

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

The description states 'Idempotently add', but annotations set idempotentHint=false, creating a direct contradiction. While the description does disclose behavior for duplicate channels (returns added=false and existing channel), the contradiction undermines trust. With annotations providing no support, the description carries the full burden but fails due to inconsistency.

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 two sentences, front-loaded with the main action and key details. Every sentence adds essential information without redundancy.

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 mentions return behavior for duplicate channels but does not describe the success case (e.g., returns added=true and the new channel). Given that an output schema exists but is not shown, and this is a mutation tool, more behavioral context (e.g., prerequisites, permissions) is expected. The description is incomplete.

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 parameters already have descriptions. The description adds value by explaining that person accepts multiple formats (ID, email, display name) and that provider labels must match a specific list. This goes beyond the schema's enum and trimming notes.

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 clearly states the action ('Idempotently add a contact channel to a person') and specifies acceptable formats for the person parameter (ID, email, display name). It distinguishes this tool from siblings like 'add_organization_channel' or 'update_person_channel' by focusing on adding a channel to a person.

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 implies usage for adding a contact channel and notes that provider labels match 'list_contact_channel_providers', but it does not explicitly state when to use this tool versus alternatives (e.g., update_person_channel) or provide exclusion criteria. Usage context is inferred but not explicitly guided.

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