Criar contato

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the description need not restate that this writes. It adds genuinely new context: the effect is a "real action visible to the customer or the team", which tells the agent the side effect is externally observable, plus the approval requirement. It stops short of saying what happens on a duplicate phone number or whether the call is idempotent, which matters for a destructive write.

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?

Three short sentences, no filler, and the identity of the tool is front-loaded before the approval constraint. Each sentence carries a distinct piece of information: what it does, what format it needs, and how consequential it is.

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 two-parameter destructive write with no output schema, the definition covers the action, the approval gate and the phone format. It is silent on the outcome of the call (does it return the new contact id, which the agent would need for follow-up aspa_send_message calls?) and on duplicate handling. Those are the gaps an agent would actually hit in practice.

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?

With schema description coverage at 50%, the description must carry more weight. It repeats the phone format guidance already in the schema (country plus area code, e.g. 5541999999999) and adds nothing about the name parameter beyond its existence, so half the inputs remain described only by minLength constraints. Useful but not compensating for the gap.

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 plus resource ("Create a new contact in Aspa") and enumerates the two fields it accepts, so an agent can distinguish it from aspa_search_contact, aspa_rename_contact and aspa_update. It never names those siblings or states the boundary explicitly, which is the only thing keeping it from a 5.

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 states a firm precondition: "Only call it after the user explicitly approved this exact action in the conversation." That is clear when-to-use guidance with an approval gate rather than a vague hint. It does not name any alternative tool for the case where the user has not approved or where the contact may already exist.

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