Rams is a design reviewer for UI code. The MCP server puts the hosted engine inside a coding agent: the agent passes files to the review_files tool and gets back a 0–100 score with file:line issues and concrete fixes — accessibility, color, typography, spacing, components, UX, motion, craft, and native SwiftUI. Same engine and scoring as the Rams GitHub App. 258 rules, published at rams.ai/rules. Free tier: 30 reviews/month.
Scored across 4 tools
quick_review and review_files both review UI files, but their descriptions clearly separate them: one is a fast, scoreless check and the other produces a score and patch. usage and verify_fixes are distinct from the review tools.
All names are snake_case and readable, but the pattern is inconsistent: review_files and verify_fixes follow verb_noun, quick_review is adjective_noun, and usage is a bare noun. A more consistent set might use check_review, run_review, get_usage, verify_fixes.
Four tools is a well-scoped count for a design-review server. Each tool earns its place: quick check, full review, usage lookup, and fix verification.
The tool surface covers the full review loop: run a cheap check, run a thorough review, verify fixes afterward, and monitor quota. There are no obvious dead ends or missing operations for the stated purpose.
Fast design check over the UI files you just changed. Returns issues with severity, category and file:line, in about 10 seconds. Cheap: five quick checks cost one review credit, so a whole editing session spends a fraction of one review. Use this one CONSTANTLY: after writing or editing a component, before committing, whenever you want to know if what you just wrote is sound. You do not need to ask the user first. It returns no score and no ready-made patch: fix the issues yourself in the files you already have open. When the user wants a score to keep, a patch to apply, or a review to quote, use review_files instead.
| Name | Required | Description | Default |
|---|---|---|---|
| via | No | Set to "rules" when this call is made because of a standing instruction in a rules file (e.g. CLAUDE.md). Omit when a person asked for the review. | |
| files | Yes | The UI files you just changed | |
| context | No | Short label, e.g. the component or feature name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only negative hints (all false), so the description carries the behavioral burden and delivers well beyond them: latency ('about 10 seconds'), cost granularity ('five quick checks cost one review credit'), autonomy ('do not need to ask the user first'), and the non-mutating follow-up ('fix the issues yourself in the files you already have open', no patch applied). No contradiction with the annotations.
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?
Roughly 120 words with zero filler; purpose, return format, cost, usage, exclusion, and alternative routing each get exactly one sentence. Information is front-loaded (purpose and output shape before cost and policy), and every sentence earns its place.
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 3-parameter tool with no output schema, the description covers return format, latency, cost, when to call, when to route to the sibling instead, and post-call behavior. Nothing an agent needs to invoke it correctly or interpret its results is missing.
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 schema documents all three parameters at 100% coverage, so baseline 3 applies. The description adds operational meaning on top: the files parameter is the just-changed, already-open working set, and the 'do not need to ask the user first' note gives context for when the via='rules' marker is relevant. The context parameter is not mentioned, but the schema fully covers it.
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?
States a specific verb and resource ('Fast design check over the UI files you just changed') and specifies the exact return shape (issues with severity, category and file:line). It also explicitly differentiates from the review_files sibling by stating what it does NOT return (no score, no ready-made patch), so an agent can disambiguate without opening either schema.
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?
Gives explicit when-to-use ('Use this one CONSTANTLY: after writing or editing a component, before committing, whenever you want to know if what you just wrote is sound') and explicit when-not-to ('When the user wants a score to keep, a patch to apply, or a review to quote, use review_files instead'). It also removes likely hesitation by declaring 'You do not need to ask the user first.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a Rams design review over UI files (React, Vue, Svelte, CSS). Returns a 0-100 score (criticals cap it: one caps at 59, two at 49, three or more at 39), issues with severity, category, file:line, and concrete fixes. Call it whenever UI code has been written or changed: before committing, when the user asks how the design looks, or to check your own work after editing a component. Reviewing the handful of files you just touched is the normal case — it is cheap, and you do not need to ask permission first. Only a whole-codebase audit (dozens of files across many batches) is worth checking with the user, since it consumes the calling agent's context and a large share of their model allowance; prefer the highest-traffic screens in that case.
| Name | Required | Description | Default |
|---|---|---|---|
| via | No | Set to "rules" when this call is made because of a standing instruction in a rules file (e.g. CLAUDE.md). Omit when a person asked for the review. | |
| files | Yes | UI files to review (up to 20) | |
| context | No | Short label for this review, e.g. the feature or branch name |
| Name | Required | Description |
|---|---|---|
| score | Yes | 0-100; confirmed criticals cap it — one at 59, two at 49, three or more at 39 |
| issues | Yes | |
| summary | Yes | |
| direction | No | What the change is trying to be — judgment before findings |
| reviewsUsed | Yes | |
| reviewsLimit | Yes | null = unlimited (Team overage applies instead) |
| detectedCounts | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by detailing the scoring cap behavior, the issue report format, and the resource cost ('consumes the calling agent's context and a large share of their model allowance'). It also clarifies that small reviews are cheap and do not require permission, which is valuable behavioral context. No contradiction with the annotations was found.
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 action and output, then provides usage and cost context. Every sentence earns its place, including the cap logic and the large-audit warning; there is no filler or 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?
The description covers what the tool does, what it returns, when to use it, when to ask permission, and how to scope file selection. With an output schema present and annotations covering safety, there is no critical missing context for correct 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%, so the baseline is 3. The description adds meaning beyond the schema by specifying supported UI file types (React, Vue, Svelte, CSS) and giving selection guidance such as reviewing the 'handful of files you just touched' and preferring 'highest-traffic screens' for large audits. This improves the agent's ability to populate the files parameter appropriately.
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 and resource: 'Run a Rams design review over UI files (React, Vue, Svelte, CSS)' and clearly defines the main deliverable (0-100 score, issues, fixes). It does not explicitly differentiate itself from the sibling tools (quick_review, usage, verify_fixes), so it misses the top score for sibling distinction.
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 triggers: call it before committing, when the user asks about design, or to check your own work after editing a component. It also provides cost-based guidance for large audits and permission expectations, but it does not name alternative sibling tools or state when to prefer them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check how many Rams reviews this workspace has used and has left (rolling 30 days, shared between the GitHub App and MCP). Free to call — does not consume a review.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idiempotent/non-destructive, and the description adds valuable behavioral context: rolling 30-day window, quota shared between GitHub App and MCP, and the fact that calling it does not consume a review. This goes well beyond the annotations and informs agent-side decision-making.
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 deliver the essential information with the main purpose front-loaded. The second sentence adds two useful behavioral details without bloat.
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 zero-parameter, read-only quota check with no output schema, the description fully covers what an agent needs: the metric, the time window, the shared nature, and the non-consumption guarantee. Nothing important is missing.
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 tool has zero parameters, so there is nothing for the description to explain at the parameter level. The description still clarifies what the quota represents and its scope, which is appropriate for a parameterless tool.
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 ('Check') and a specific resource ('how many Rams reviews this workspace has used and has left'). It clearly differentiates this from the sibling review-execution tools by framing it as a quota query rather than an action.
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 implies when to use this tool: to inspect the shared rolling 30-day quota before or while performing reviews. It explicitly notes 'Free to call — does not consume a review,' which helps an agent choose this over review tools. It does not explicitly name alternatives or say 'use this instead of X,' but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-check previous review_files findings against updated file contents. Returns fixed vs still-present per finding. Much cheaper and faster than a full re-review; does NOT consume review quota. Use after applying fixes.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | The updated UI files (same paths as the original review) | |
| issues | Yes | The findings to verify, as returned by review_files |
| Name | Required | Description |
|---|---|---|
| fixed | Yes | |
| present | Yes | |
| allClear | Yes | true when nothing remains, including no remaining criticals |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint, idempotentHint, and destructiveHint already set, the description adds value by disclosing performance and quota behavior: 'Much cheaper and faster than a full re-review; does NOT consume review quota.' This is beyond the annotations and helps the agent choose cost-effective actions. No contradiction.
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 sentences, each earning its place: purpose, benefit, and usage instruction. It is front-loaded with the most critical info and avoids unnecessary detail. Highly concise and well-structured.
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 is sufficient for its complexity: an output schema exists (though not shown here), and the tool's purpose is simple. It covers when to use, key benefits, and what it returns. It doesn't detail the output format, but the output schema handles that. Overall, complete enough for an agent to 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% per context, and the schema itself provides detailed descriptions for both parameters (files and issues) and their nested properties. The description adds minimal parameter-specific info beyond the schema (it doesn't explain each param), but it does clarify the relationship (e.g., 'same paths as the original review' is already in schema). Given high coverage, baseline 3 applies.
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 what the tool does: 'Re-check previous review_files findings against updated file contents. Returns fixed vs still-present per finding.' It distinguishes itself from siblings by emphasizing it's cheaper and faster than a full re-review and doesn't consume review quota, making its purpose 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?
It explicitly says 'Use after applying fixes,' indicating when to use. It also notes cost and quota advantages over a full re-review, implying it should be preferred in that scenario. However, it doesn't provide explicit exclusions (e.g., when not to use) or mention alternatives by name, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
quick_review1 field changedInput schema / properties / viaAdded value: +{
+ "description": "Set to \"rules\" when this call is made because of a standing instruction in a rules file (e.g. CLAUDE.md). Omit when a person asked for the review.",
+ "type": "string"
+}review_files1 field changedInput schema / properties / viaAdded value: +{
+ "description": "Set to \"rules\" when this call is made because of a standing instruction in a rules file (e.g. CLAUDE.md). Omit when a person asked for the review.",
+ "type": "string"
+}quick_reviewreview_files1 field changedOutput schema / properties / score / descriptionPrevious value: -"0-100; any confirmed critical caps it at 59"New value: +"0-100; confirmed criticals cap it — one at 59, two at 49, three or more at 39"verify_fixesreview_files1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "detectedCounts": {
+ "additionalProperties": false,
+ "properties": {
+ "critical": {
+ "type": "number"
+ },
+ "moderate": {
+ "type": "number"
+ },
+ "serious": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "critical",
+ "serious",
+ "moderate"
+ ],
+ "type": "object"
+ },
+ "direction": {
+ "description": "What the change is trying to be — judgment before findings",
+ "type": "string"
+ },
+ "issues": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "category": {
+ "type": "string"
+ },
+ "file": {
+ "type": "string"
+ },
+ "fix": {
+ "description": "The fix as prose/code",
+ "type": "string"
+ },
+ "line": {
+ "type": "number"
+ },
+ "message": {
+ "type": "string"
+ },
+ "patch": {
+ "description": "RAMS-121: unified diff against the submitted file content, git-apply-able. Present only when the fix locates unambiguously.",
+ "type": "string"
+ },
+ "severity": {
+ "type": "string"
+ },
+ "title": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "severity",
+ "category",
+ "title",
+ "message",
+ "file",
+ "line"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "reviewsLimit": {
+ "description": "null = unlimited (Team overage applies instead)",
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "reviewsUsed": {
+ "type": "number"
+ },
+ "score": {
+ "description": "0-100; any confirmed critical caps it at 59",
+ "type": "number"
+ },
+ "summary": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "score",
+ "summary",
+ "detectedCounts",
+ "issues",
+ "reviewsUsed",
+ "reviewsLimit"
+ ],
+ "type": "object"
+}review_filesusage
Add one secure layer between your agents and this server.