Add Person Alias

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

Annotations indicate a non-read-only, non-destructive write operation. The description adds cost ($0.05) and API key requirement, which are not in annotations. However, it does not disclose behavior like duplicate handling or error responses. The added context is useful but limited.

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 sentence that front-loads the core purpose (add alias) and appends cost/auth details. It contains no filler or redundant information, making it highly concise and well-structured.

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?

With six parameters, only two required, and schema covering only idempotency keys, the description leaves critical parameters like source and alias_kind unexplained. It also does not mention idempotency behavior despite having request_id fields. The output schema exists, but the description provides insufficient guidance for correct invocation, especially for optional parameters and expected outcomes.

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 low (33%) with only idempotency keys described. The description gives hints about the 'alias' parameter via examples but leaves person_id, source, and alias_kind unexplained. With low coverage, the description should compensate but does not adequately clarify the required and optional parameters.

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 verb 'Add' and the resource 'alias' for a CRM person, with examples of alias types (nickname, payment handle, misspelling). This differentiates it from siblings like remove_person_alias and update_person_alias by explicitly indicating an additive operation.

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 when to use the tool (to add an alias) but does not explicitly mention alternatives or state when not to use it. There is no reference to update or remove operations, leaving usage guidance solely implied by the 'Add' wording.

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