Convert Contact Entity

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the description's job is to add behavioral detail beyond that. The description notes 'Preserves FKs', which is a useful behavioral guarantee that foreign keys are not broken, and mentions pricing ($0.10) and API key requirement, adding context not in annotations. However, it doesn't disclose whether the operation is reversible, what happens to existing relationships, or what the output looks like, though an output schema exists. The description does not contradict annotations, so no contradiction flag.

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 one sentence with high information density: it states the action, its equivalence to a sibling, a key guarantee (preserves FKs), and operational details (pricing, API key). Every word earns its place, no fluff or redundancy. It's front-loaded with the core purpose before the parenthetical notes.

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?

Given the schema has 5 parameters with low coverage, an output schema exists, and the operation is a simple conversion, the description is fairly complete. It covers the core action, equivalence, FK guarantee, and cost/auth details. However, it could be enhanced by clarifying the difference between entity_id and person_id and the allowed target_type values, but the output schema and annotations help. It's not fully complete but adequate for a straightforward mutation tool.

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 only 40%, so the description must compensate for undocumented parameters. The description mentions 'entity_type' which maps to 'target_type' parameter, but does not explain the meaning of 'target_type' values or the roles of 'entity_id' vs 'person_id'. It also hints at 'request_id' via idempotency context, but not fully. The description adds some value by referencing entity_type, but leaves ambiguity about which identity parameter to use and target enum values. Baseline is 3 due to moderate coverage, but description doesn't fully compensate.

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 states a specific verb ('Convert') and resource ('a contact's entity_type'), which clearly conveys the operation. It also references a sibling tool 'classify_contact', noting they are the same operation, which helps distinguish it from other contact/property tools. However, it doesn't explicitly state the purpose beyond the action, like what conversion means in terms of the domain, but the verb and resource are clear enough.

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 explicitly mentions 'same as classify_contact', which signals to the agent that this tool is equivalent to a sibling, but does not provide explicit when-to-use vs alternatives or when NOT to use it. The mention of preserving FKs is a key usage hint, implying it's safe to convert without breaking relationships. However, it lacks clarity on conditions like whether the contact must be a person or company, or why you'd choose this over classify_contact.

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