Rams

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

Annotations provide no behavioral hints (all false), so the description carries the burden. It discloses cost (five quick checks per credit), speed (~10 seconds), and the fact that it returns no score or patch. This is valuable context, though it could explicitly state that it does not modify files.

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 front-loaded with the core purpose and result (issues with severity, category, file:line). It then covers cost, usage, and exclusions in a logical order. Slightly wordy at the end ('so a whole editing session spends a fraction of one review') but every sentence adds meaningful guidance.

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 100% schema coverage and no output schema, the description covers all essential context: what it does, when to use it, when not to use it (review_files), cost, speed, return behavior (no score/patch), and autonomy (no need to ask user). Combined with the schema, it is fully 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?

Schema description coverage is 100%, so the baseline is 3. The description adds context that the files are 'UI files you just changed' and that the context parameter is a 'Short label', but these are already reflected in schema descriptions. The tool description provides no additional parameter-level details beyond what the schema already documents.

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 a specific verb and resource: 'Fast design check over the UI files you just changed. Returns issues with severity, category and file:line.' This distinguishes it from the sibling review_files tool, which is described as the alternative for scores and patches.

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 usage guidance: 'Use this one CONSTANTLY: after writing or editing a component, before committing, whenever you want to know if what you just wrote is sound.' It also names the alternative: 'When the user wants a score to keep, a patch to apply, or a review to quote, use review_files instead.'

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?

The description discloses score cap behavior (one critical caps at 59, two at 49, three or more at 39), which is a notable behavioral trait not covered by annotations. It also states the operation is 'cheap' and doesn't require permission, plus warns about context/allowance consumption for large audits.

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 front-loaded with the main action and output, then expands to usage guidance and cost caveats. While longer than average, every sentence conveys distinct, useful information without repetition.

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?

The description fully covers the tool's behavior, return values (with caps and issue details), usage contexts, and cost implications. An output schema exists for return structure, so the description doesn't need to duplicate that. No significant gaps remain.

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 input schema has 100% description coverage for both parameters, so the baseline is 3. The description adds value by specifying which file types count as UI files (React, Vue, Svelte, CSS), and implies the 'files' parameter expects path/content objects, slightly enriching the 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 runs a Rams design review over UI files and specifies supported frameworks (React, Vue, Svelte, CSS). It differentiates from siblings by describing the review's output (score, issues, fixes) and use case.

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 explicitly says to call it 'whenever UI code has been written or changed' and lists specific scenarios. It also provides an exclusion: whole-codebase audits should be checked with the user first, giving clear when-not guidance.

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?

Annotations already indicate read-only and idempotent behavior. The description adds valuable behavioral context: the quote is shared between the GitHub App and MCP, the rolling 30-day period, and the explicit guarantee that calling it does not consume a review. These details go beyond the annotations and help the agent understand side effects.

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 a single, well-structured sentence that front-loads the core purpose and then provides essential qualifiers in parentheses. Every phrase adds value: the quota metric, the rolling window, the shared source, and the no-consumption guarantee.

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 no-parameter, no-output-schema tool, the description is fully sufficient. It explains what the tool checks, the relevant time period, the sharing context, and that the call is free. The agent has everything needed to invoke it correctly and interpret the result.

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?

There are no parameters (0 params), so per calibration baseline is 4. The description doesn't need to explain parameters, and it appropriately explains what the tool inspects rather than any input details.

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 uses a specific verb ('Check') and explicitly names the resource ('Rams reviews quota'), stating what is measured (used and left) and the rolling 30-day window. This clearly distinguishes it from sibling tools like review_files and verify_fixes, which actually perform reviews.

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 conveys when to use the tool by emphasizing that it is 'Free to call' and 'does not consume a review', implying it should be used to check quota before calling review-consuming tools. It does not explicitly mention alternatives or exclusions, but the context from siblings and the safety note provide meaningful usage guidance.

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?

The description adds valuable behavior beyond annotations: it discloses cost/performance traits ('cheaper and faster') and quota effects ('does NOT consume review quota'). Annotations already provide idempotent and non-destructive hints, and the description supplements them with return semantics. Minor gap: it does not explicitly mention whether any state changes occur, but the term 'Re-check' and annotations make this a low concern.

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 extremely concise, using three sentences to convey purpose, output, usage, and cost. It is front-loaded and contains no fluff or repetition.

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 verification tool, the description covers the essential context: what it does, what it returns, when to use it, and the main alternative. The input schema fully documents parameters, and the description adequately describes the output behavior. No critical gaps remain.

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%, so the schema already explains both parameters. The description adds context by referring to 'updated file contents' and 'previous review_files findings,' which aligns with the 'files' and 'issues' parameters, but it does not add new format or syntax details beyond the 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 a specific verb and resource: 'Re-check previous review_files findings against updated file contents.' It also specifies the output ('Returns fixed vs still-present per finding') and differentiates from the sibling tool review_files by focusing on verification rather than full review.

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 'Use after applying fixes' and provides contextual guidance: 'Much cheaper and faster than a full re-review; does NOT consume review quota.' This tells the agent when to use it and contrasts it with the alternative (review_files).

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