send_personal_message

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

With no annotations at all, the description carries the full disclosure burden, and it does add non-obvious behavior: no desktop helper is required, replies are scoped to the originating session, the wait is bounded and non-waking, and resend-after-uncertainty is discouraged (implying at-most-once delivery). It omits failure/error behavior, delivery guarantees, and permission or scope constraints beyond the vague "within the human's existing scope."

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?

Five short sentences, all front-loaded with the core action first and constraints after. Almost every sentence carries information, though "Talk directly" is imprecise wording that costs a little 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 7-parameter messaging tool with no annotations and no output schema, the description is too thin: it does not explain what 'to' identifies, what a caller gets back (delivery confirmation? reply content?), or what happens when no reply arrives within wait_seconds. The async/session semantics hint is helpful but not sufficient.

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 0% across 7 parameters, so the description must compensate. It touches on id ("use a stable id"), wait_seconds ("bounded wait"), scope ("the human's existing scope"), and implicitly expects ("retrieves an answer"), but 'to', 'sender', and the expects enum values are never explained, nor is the 30-second cap.

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 says it will "talk directly to a discovered personal agent within the human's existing scope," which conveys sending a message to a peer agent, but the verb is loose ("talk") rather than a precise action like "send a message." It never names the sibling it differs from (e.g. reply_personal_message, send_message), so an agent must infer the distinction from the shared "personal_" namespace.

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 gives real operational guidance — reuse a stable id and never auto-resend after uncertainty — and clarifies the bounded-wait behavior ("does not wake an idle local session later"). However, it never states when to choose this over reply_personal_message, send_message, or ask_dispatcher, which is the key selection decision among the siblings.

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