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

Annotations declare idempotentHint=true and readOnlyHint=false, and the description reinforces this usefully: it creates a conversation only when none exists, sends no message, and tells the caller to reuse idempotency_key on retries. It does not say what permissions are needed or what is returned, but the safety-relevant behavior is well covered.

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 with the core action front-loaded and no filler. The UI analogy ("as the inbox search's Text <number> does") is compact but assumes product familiarity, and "nobody is saved under" could be reworded for clarity.

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 create-or-find tool with no output schema, an agent still lacks an explicit statement of what comes back (conversation id/object) and what happens when multiple conversations exist. Required behaviors — no message sent, idempotent retries — are covered, so it is adequate but not complete.

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 50%: idempotency_key is fully documented in the schema, while phone has only length bounds. The description adds real meaning for phone (an unsaved number, matching inbox search syntax) but no format guidance such as E.164 or country code, so it only partly compensates.

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?

States a specific verb and resource with find-or-create semantics ("Opens (or finds) the one conversation for a phone number"), which no sibling shares. The qualifier "nobody is saved under" is awkwardly phrased and takes a moment to parse, but the overall intent is clear.

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?

Conditions the tool on a phone number with no saved contact and anchors it to a familiar inbox behavior ("Text <number>"), and "Nothing is sent" steers the agent away from send_text. It stops short of naming explicit alternatives such as link_conversation_to_client for existing contacts.

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