preview_save_online_submission

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

Annotations already declare readOnlyHint=true, so the read-only nature is disclosed. The description adds the specific scope (replacement of online text) and reinforces that it never modifies the submission, which is consistent with the annotation. However, it does not disclose what the preview actually returns or any other behavioral details, such as whether it validates input or checks permissions. Since annotations cover the safety profile, the description adds minimal extra context.

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 in Spanish: 'Previsualiza el reemplazo del texto online; nunca modifica la entrega.' It is front-loaded with the core action and includes the key side-effect disclaimer. Zero waste, no redundancies.

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 3 parameters (0% schema coverage) and no output schema, the description is insufficient. It does not explain what the preview reveals, what the agent should do with the response, or what the parameters mean. The readOnlyHint annotation provides safety context, but functional completeness is lacking; the agent is left guessing about course_module_id's relevance and the nature of the preview result.

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 not mention any of the parameters (assignment_id, online_text, course_module_id) or their roles. The phrase 'reemplazo del texto online' only loosely relates to online_text but does not explain what it means or how it interacts with assignment_id or course_module_id. No parameter meanings are added beyond the bare schema.

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 tool's purpose: it previews the replacement of online text and explicitly notes it never modifies the submission. The verb 'previsualiza' (previews) and resource 'reemplazo del texto online' (replacement of online text) are specific, and the mention of 'nunca modifica la entrega' distinguishes it from the sibling save_online_submission.

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 does not explicitly name the alternative or state when to use this tool vs. save_online_submission. The phrase 'nunca modifica la entrega' implies that if modification is intended, another tool should be used, but this is not made explicit. No direct guidance on when to choose this tool over its siblings is provided, though the preview/action pattern among siblings offers implied context.

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