Save standardized IELTS review

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

Annotations declare readOnlyHint=false and destructiveHint=false, which already indicate this is a write (non-readonly) operation that isn't destructive. The description adds that it saves 'the fixed-format Markdown review' and 'its machine-readable JSON record', giving some specification about what gets persisted. It doesn't mention overwrite behavior, ID association, or whether the session must exist first.

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?

A single, concise sentence that fronts the verb and resource clearly. Every word earns its place - no filler, no redundancy, efficient delivery of purpose.

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 2 required params, 0% schema coverage, and no explanation of the fixed format or how sessionId relates, some gap remains. The output schema exists but its content isn't shown in the definition. The description adequately covers the core save action but omits details about the reportJson format requirements and session association semantics.

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 burden for parameter meaning. It references reportMarkdown (fixed-format Markdown review) and reportJson (machine-readable JSON record), adding meaning beyond the bare schema. However, it doesn't explain the 'fixed format' specifics, required format of reportJson, or the role of sessionId (which is optional in 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 states a clear action: saving a fixed-format Markdown review and its JSON record after a practice session. It identifies the two artifacts (reportMarkdown, reportJson) and the timing ('after a practice session'). However, it doesn't distinguish from potential siblings like list_practice_history, though those are reading tools, so sibling differentiation is less critical here.

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 conveys this is used post-practice-session to persist review artifacts. It doesn't explicitly state when NOT to use it or name alternatives, but the context (after a practice session) is clear. No exclusions or alternative tool references are provided.

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