skill.diff

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

With no annotations, the description carries the full burden. It discloses the return format (unified diff) and the two diffing modes, which is useful. However, it does not address authentication, existence/error behavior for unknown versions, or read-only nature, leaving real gaps for a no-annotation tool.

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?

Two short sentences, front-loaded with the core purpose followed by the actionable next-step hint. Every clause earns its place with no filler.

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?

There is no output schema, so the description need not explain returns—yet it names the unified diff format, which is a bonus. Combined with the skill.versions pointer, it is nearly complete for a 4-param read tool; only the two undocumented required params leave a small hole.

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 only 50%: to_version and against_body are documented in the schema, while skill_id and from_version are bare. The description partly compensates by explaining the two-version mode and pointing to skill.versions for version labels, but it never clarifies what skill_id or from_version expect beyond the obvious.

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 specific verb (return a unified diff) on a specific resource (two versions of a skill), and clarifies the two modes: version-to-version or live-vs-arbitrary-string. It distinguishes itself from the sibling skill.versions by describing their complementary relationship rather than overlapping it.

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?

It gives an explicit prerequisite/first-step: 'Use skill.versions first to find version labels,' which tells the agent how to obtain inputs. It lacks explicit when-not guidance or exclusions (e.g. use skill.compareVersions for semantic comparison), so it stops short of a 5.

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