compare

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context by disclosing that the comparison is both textual (word-by-word) and visual, which is not in the annotations. It stops short of noting format compatibility, ordering effects, or size/rate limits.

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 no filler; the core action and its two comparison modes come first. It is efficient, though the brevity is partly under-specification rather than true conciseness given the undocumented parameters.

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?

An output schema exists, so return values need not be described. However, with 0% schema coverage, no usage guidance, and no indication of supported file types or the meaning of the two required paths, the description leaves significant gaps for a two-parameter tool.

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% – the two required parameters carry only titles ('Path A', 'Path B'). The description implies both are document versions being compared but never states whether these are file paths, relative paths, or document IDs, nor whether path_a/path_b order affects the diff output. It does not compensate for the coverage gap.

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 names a specific verb (compare) and resource (two versions of a document) and even specifies the comparison modes: word-by-word and visual. That is enough for an agent to know exactly what the tool produces. It does not, however, contrast itself with any sibling, though none of the listed siblings appear to offer document diffing.

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?

There is no when-to-use statement, no prerequisites (e.g. both documents must be readable/parsed), and no mention of alternatives such as read_text for extracting a single document. The agent must infer all routing decisions from the one-line purpose.

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