oasdiff

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

No annotations are present, so the description carries the burden. It discloses the return type ('breaking and warning-level changes') and a key limitation ('Both specs must be valid, self-contained OpenAPI... external $ref URLs or files are not resolved'). It does not explicitly state read-only behavior, but that is reasonably inferred from the comparison nature.

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?

The description is three focused sentences: purpose, usage guidelines with alternatives, and a constraint. Every sentence adds value without redundancy.

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?

Given the simple parameter structure (2 required strings) and no output schema, the description covers what the tool does, its inputs, its output type, and its constraints. It is complete for an AI agent to select and invoke correctly.

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 100% (both parameters have clear descriptions in the schema). The description adds little beyond repeating that specs are YAML or JSON, so the baseline score of 3 is appropriate.

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 clearly states the tool's purpose: 'Detect breaking API changes between two OpenAPI specifications.' It distinguishes from siblings by noting when to use this tool versus alternatives like oasdiff_changelog, oasdiff_diff, and oasdiff_validate.

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?

Explicit guidance is provided: 'Pass the base (old) and revision (new) specs as YAML or JSON.' It also tells when to use this tool ('when the question is whether an API change breaks existing clients') and offers clear alternatives for other use cases.

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

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

No annotations are provided, so the description carries full burden. It discloses that it detects all changes including informational, accepts YAML/JSON, and requires two specs. It does not explicitly state output format or error handling, but the core behavior is sufficiently transparent.

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?

The description is efficient, front-loaded with purpose, then usage guidance and constraints. Every sentence adds value, and it is appropriately sized for the tool's simplicity.

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?

Given the tool has only two string parameters with good schema descriptions and no output schema, the description covers the essential context: purpose, usage guidance, and constraints. It sufficiently explains what the tool does and when to use alternatives, though it does not describe the output structure.

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% with clear parameter descriptions. The description adds value by clarifying that both inputs must be valid, self-contained OpenAPI specs, and that they can be YAML or JSON. This extra context justifies above baseline.

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 clearly states the tool produces a full changelog of every detected change between two OpenAPI specs, including informational changes. It distinguishes from siblings by explicitly naming alternatives and their purposes.

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 explicitly says when to use this tool ('when you want the complete set of changes at every severity') and provides direct alternatives with usage guidance. It also specifies preconditions about specs being valid, self-contained, and not using external refs.

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

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

No annotations provided, so description carries burden. It clearly indicates the tool is a read-only diff (no modification implied), but doesn't explicitly state non-destructive nature or mention any rate limits/auth. However, the diff behavior is transparent from the description.

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?

Four sentences front-load purpose, then usage, alternatives, and constraints. No wasted words, well-structured and easy to parse.

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?

Given the tool's simplicity (two string inputs, no output schema), the description covers purpose, when to use, alternatives, and constraints. It is complete and leaves no major gaps for an agent to understand invocation.

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% (both params described), so baseline is 3. Description adds context (old vs new, YAML/JSON) but this largely matches existing schema descriptions. No additional semantic value beyond 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 clearly states the tool shows the structural diff between two OpenAPI specs, listing what was added, removed, or modified. It distinguishes from siblings by specifying it's for raw structural changes, not backward-compatibility or severity-classified changelog.

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?

Explicitly says when to use this tool (for raw structural changes) and when not (use oasdiff_breaking_changes or oasdiff_changelog for other purposes). Also states constraint that both specs must be valid, self-contained OpenAPI, no external refs.

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

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

With no annotations provided, the description bears full burden. It reveals input format acceptance (YAML/JSON), output nature (findings, empty if valid), and a key constraint (external refs not resolved). Lacks details on error handling or performance, but adequate for a simple validation 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 concise sentences, each earning its place. First sentence states primary purpose and return format. Second sentence provides usage guidance and limitation. Front-loaded and minimal.

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?

With no output schema, the description explains return value (findings, empty for valid). It covers input, purpose, and constraints. Could mention format of findings but not essential. For a simple 1-param tool, it is sufficiently complete.

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?

The single parameter 'spec' is described in schema as 'the OpenAPI specification to validate, as YAML or JSON'. The description adds value by emphasizing self-containment requirement, which is not in schema. With 100% schema coverage, baseline is 3; extra context justifies 4.

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 explicitly states it validates a single OpenAPI specification against rules, using clear verb 'validate' and resource 'single OpenAPI specification'. It distinguishes from sibling tools that compare two specs, providing specific purpose.

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 gives explicit when-to-use (single spec validation), when-not-to-use (specifies comparing two specs should use oasdiff_breaking_changes, oasdiff_changelog, or oasdiff_diff), and a limitation (spec must be self-contained). This clearly guides selection.

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