send_message

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it returns a task_id immediately (asynchronous), request_id reuse with the same payload is idempotent, and it can reply to structured permission/elicitation IDs. It does not discuss auth or rate limits, but for a tool with annotations that is not a major gap.

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 three sentences and front-loads the primary purpose. Every sentence adds information (async return, idempotency, reply capability), though the third sentence is slightly vague about how the structured ID is used.

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 tool with 8 optional parameters, nested object content, an enum, and no output schema, the description is incomplete. It does not explain parameter combinations (e.g., what is required to reply to a permission versus send a normal message), the meaning of elicitation_action values, or the roles of cwd and session_id. The core behavior is covered, but the definition is not complete enough for reliable invocation.

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 8 parameters, so the description carries the full burden. It explains idempotency for request_id and hints at reply_to_interruption_id / permission_option_id via 'structured ID,' but leaves cwd, message, session_id, elicitation_action, and elicitation_content entirely undocumented. The partial compensation is not enough for this many 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 states a specific verb and resource: 'Start or continue a dedicated WorkBuddy conversation,' and adds that it returns a task_id and can reply to permissions/elicitations. It does not explicitly differentiate itself from siblings like get_message or wait_for_message, so it stops short of 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 implies when to use the tool (starting or continuing a conversation, replying to a pending permission or elicitation) but gives no explicit exclusions or named alternatives. An agent can infer usage, but there is no guidance on when to choose this over get_message or wait_for_message.

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