Diff two texts

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the description spends its budget on operationally useful detail: 3 lines of unified-diff context, the [-old-]/{+new+} inline markers, added/removed/unchanged counts, and a hard 50,000-line-per-side limit. What's missing is any hint about the response envelope (field names/shape), which matters more here because there is no output schema.

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?

Purpose, output format, limits and options are front-loaded in one dense sentence, followed by short supporting clauses. 'Works with any language (Arabic included)' and the demo URL are mildly peripheral but small enough not to bloat the definition.

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 9-parameter tool with no output schema, the description does the heavy lifting on return values, size limits and diff semantics, and annotations cover side-effect safety. The remaining gap is that zero parameters are required and nothing states that you must supply either the two text fields or the two path fields — an agent can call this with an empty object and get no warning from the description.

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 coverage is 100%, so every parameter is already documented with defaults; the description only restates the whitespace/case toggles and the word-level marking behavior. It adds no semantics for the nameA/nameB header labels or for the mutually exclusive inline-text vs. *Path input modes, which is exactly the ambiguity the schema alone leaves open.

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?

Names a specific verb (compare), resource (two texts), algorithm (Myers diff), and output artifact (unified diff with counts and change blocks). This clearly separates it from ai_image_diff (images) and ai_text_similarity (scoring), though it never names a sibling explicitly to make the routing unambiguous.

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 by the verb 'compare' — there is no statement of when to prefer this over ai_text_similarity or which input mode (inline text vs. *Path file inputs) to pick. The mention that whitespace/case can be ignored hints at use cases (formatting-insensitive comparison) but stops short of guidance.

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