review_spelling

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the phrase 'without changing text or attributed quotes' usefully clarifies that quotes are outside the rewriting scope. However, it does not say how findings are reported, whether suggestions or a pass/fail verdict are returned, or how the approvedWords list influences results.

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 front-loaded sentence with the verb and scope first and no filler. It is tight, though the brevity leaves no room for the missing parameter guidance rather than being genuinely complete.

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 a required nested object, an enum parameter, and an unfamiliar approvedWords list, plus no output schema, the definition is too thin. It never explains the fields structure or the return shape, so an agent must guess at invocation details the description was supposed to supply.

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 carry the load, and it only partially does: 'English or Swedish' maps to the language enum, but the required nested 'fields' object (string keys to max-6000-char values) and 'approvedWords' are never explained. An agent cannot tell from the description what field keys are expected or what approvedWords does.

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 gives a specific verb+resource ('Review ... spelling') plus a language scope (English or Swedish) and a non-mutation constraint. No sibling in the provided list performs spelling review, so differentiation is implicit rather than explicit, which keeps it just short of a 5.

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?

Usage is only implied: an agent can infer this is the tool for checking spelling before publishing, but the description never names an alternative (e.g., validate_* or qa_* tools) or states when not to use it. No prerequisites or workflow placement are given.

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