preview_message

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

Annotations declare readOnlyHint=true and destructiveHint=false, which already indicate a non-destructive operation. The description adds value by specifying that it creates a token and never sends, which is important behavioral context beyond the annotations. It does not contradict the read-only hint because token creation is not a data mutation; the description is consistent and informative.

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, concise sentence that front-loads the primary purpose ('Previsualiza un mensaje Moodle') and immediately clarifies the key distinction ('nunca realiza el envío'). It has zero wasted words and is easy to parse quickly.

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 two obvious parameters and no output schema, the description covers the core behavior but leaves out important context: what the returned token is for, how it should be used (likely for a later send), and any expiry or validity constraints. Since these details are critical for an agent to use the tool correctly, the description is incomplete, though not severely inadequate for a simple preview operation.

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 carries the full burden of explaining parameters. However, the description does not mention recipient_user_id or text at all. While the parameter names are self-explanatory to a degree, the description fails to clarify their meaning, purpose, or any constraints, leaving the agent to infer from the schema alone. This is a significant gap given zero schema coverage.

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 clearly states the verb ('previsualiza'), the resource ('mensaje Moodle'), and the action ('crea un token'), and explicitly distinguishes it from sending by saying 'nunca realiza el envío'. This differentiates it from the sibling 'send_message' without ambiguity.

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?

The description gives clear context: it is a preview that never sends. This implies it should be used before any actual sending, with 'send_message' as the alternative for sending. However, it does not explicitly name the alternative or provide a when-not condition beyond 'nunca realiza el envío', so it falls short of the highest bar.

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