send_message

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

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Send a message,' implying a mutation, but it does not mention required authentication, side effects (like notifications to recipient), rate limits, or success/failure behavior. This is a significant gap for an action tool.

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 a single, focused sentence that front-loads the purpose and then gives a practical detail about recipient_id. There is no redundancy or fluff; every word earns its place.

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 three parameters and no output schema, the description leaves too much unstated. It does not explain the body parameter, what subdomain means or when to override it, whether login is required, or what the call returns. The recipient_id hint is good but insufficient 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%, so the description must compensate. It does clarify the recipient_id format and points to lookup tools, which is valuable. However, it leaves body and subdomain undefined. body is likely the message content but not explicitly stated, and subdomain is not explained at all. Partial compensation only.

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 clear verb ('Send') and resource ('a message') with a recipient, and it explicitly defines the recipient_id format. It stands apart from all sibling tools (which are mostly get_* or auth-related), so there is no ambiguity about what this tool does.

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?

There is no guidance on when to use this tool versus alternatives, nor any exclusions. The only hint is pointing to get_students/get_teachers for recipient_id formatting, which is about parameter values, not usage context. No mention of prerequisites (e.g., being logged in) or when not to use it.

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