grove_send_message

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

Annotations (readOnlyHint: false) are minimal, so the description carries the transparency burden — and it delivers: auto-creation side effect, the sender default oddity (never a literal "Auto"), the grove_relay permission requirement, and the sender_forbidden error. This meaningfully extends beyond the structured annotation fields without contradiction.

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?

Front-loaded purpose and side effect, followed by an efficient Args block. At ~90 words it is efficient with no redundancy, and the per-parameter docs are terse but complete. It earns the length.

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 mutation tool with no output schema, the description omits what the call returns (Ack? Message object?) and leaves app_id undocumented. The identity/permission contract is admirably complete, but the missing parameter and no return contract keep it from being fully self-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%, so the description must compensate — and it covers 3 of 4 parameters with real behavioral detail (defaults, permission fallbacks). Unfortunately, app_id is entirely undocumented, leaving a gap for the agent on that parameter.

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 ('Send'), resource ('a message to a Grove channel'), and a unique side effect ('Creates the channel if it doesn't exist'). The purpose is immediately clear and distinguishable from the many sibling tools, though no specific sibling is named to sharpen the contrast.

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?

Provides the permission prerequisite ('Requires grove_write') and default behaviors, which tells the agent when it is permitted to use the tool. However, it does not say when NOT to use it or point to alternatives like grove_reply or grove_bus_send for different intents.

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