Raven MCP

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.2.9
Disambiguation3/5
Many tools have distinct purposes, but there is significant overlap among audit tools (e.g., audit, audit_page, audit_url, audit_screen, audit_ios_screen) and between decision- and taste-related tools. The sheer number (104) makes it hard for an agent to quickly distinguish which tool is appropriate without careful reading, though descriptions are detailed.
Naming Consistency4/5
Most tools follow a consistent verb_noun pattern (e.g., get_principles, create_brand_profile, audit_page). There are a few irregularities like talon_scan, raven_reflect, and init_design_md, but overall the naming is predictable and clear.
Tool Count2/5
With 104 tools, the server is far beyond the typical well-scoped range (3-15). While the domain is broad (design, audits, generation, taste, etc.), many tools are highly specialized and could be consolidated. The count feels excessive and likely to overwhelm users and agents.
Completeness4/5
The tool surface covers an impressively wide range: design principles, UI patterns, audits (various types), design system management, content guidance, creative generation, taste profiling, and decision tracking. Minor gaps exist (e.g., no direct UI builder), but for a design evaluation and guidance server, the coverage is thorough.
Average 4/5 across 104 of 104 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- 9 of 10 community issues answered or closed in the last 6 months
- 781 commits in the last 12 weeks
- Last stable release on July 17, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, indicating this is a potentially destructive write operation. The description adds minimal behavioral context beyond that—it does not explain what is destroyed (e.g., overwrites existing rationale?), whether the operation is reversible, or what state the decision node must be in (e.g., must be a draft). It essentially restates the annotation implications without new details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8 words, which is appropriately concise. It front-loades the action and resource without unnecessary words. However, it could add a bit more useful information without becoming verbose, so it does not achieve a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (2 required) and no output schema, the description is incomplete. It does not explain what happens after committing (e.g., return values, side effects on related data). It omits prerequisites (e.g., 'decision_draft' must have been used first) and error conditions. For a potentially destructive action, more context is needed for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 no additional meaning to the parameters beyond what the input schema provides. For example, it does not explain that 'similarity_threshold' overrides an environment variable for this commit, nor does it clarify the difference between 'commit' and 'confirm' in terms of parameter handling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'commit or confirm' and specifies the resource as 'rationale for a draft or extracted decision.' It clearly indicates the action and target, though the dual verbs introduce slight ambiguity. It distinguishes from siblings like 'decision_draft' and 'decision_evidence' by focusing on finalizing the rationale, but doesn't explicitly contrast with all related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. It lacks explicit context about prerequisites (e.g., required existence of a draft) or situations where another tool like 'decision_supersede' or 'decision_add' might be more appropriate. No alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, indicating state mutation. The description adds no further behavioral details beyond the basic add operation. It does not contradict annotations, but it does not elaborate on side effects, permissions, or what 'active' means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is appropriately front-loaded. However, it could be slightly expanded to include usage guidance without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple add operation with 6 params, the description is minimal. It doesn't explain the Decision Graph context, what happens on success, or the meaning of 'active'. Given no output schema, some additional context would help agents fully understand the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 6 parameters have descriptions in the schema. The tool description adds no additional parameter context, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Add') and the resource ('active decision') and specifies the target ('local Decision Graph'). The purpose is unambiguous, though it does not explicitly differentiate from sibling decision tools like decision_commit or decision_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., decision_commit, decision_draft). There is no mention of prerequisites, context, or when to avoid using it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds minimal behavioral context beyond annotations. Annotations already indicate destructiveHint=true, and description confirms a capture operation but doesn't clarify what gets destroyed, whether it overwrites, or any side effects. No extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence with zero waste. Every word carries meaning, front-loading the action and key nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 4 parameters (3 required) and destructiveHint=true, the description is too brief. It doesn't explain return behavior, success criteria, or how 'deferred' confirmation works. With no output schema, more completeness is needed for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a description. The tool description does not add additional parameter-level details, so it meets the baseline. No extra value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description provides a specific verb 'Capture' and resource 'a decision', with a unique nuance about deferring the 'why' for later confirmation. It clearly distinguishes from sibling decision tools like 'decision_commit' and 'decision_add' by indicating a provisional capture.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. With many sibling decision tools (e.g., decision_commit, decision_add, decision_scope), the description should indicate that this is for tentative captures needing later confirmation, but it doesn't.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description claims a read operation ('Get'), but annotations have destructiveHint: true and readOnlyHint: false, indicating potential side effects. This contradiction renders the description misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the key verb and resource, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, yet description does not specify the response format (e.g., structure, pagination). The contradictory destructive hint also undermines completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'id' described as 'Decision Graph node id'. Description adds no further meaning beyond the schema, achieving baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool gets a Decision Graph node and all connected nodes via edges. This is specific and distinguishes from sibling tools like decision_list and decision_add.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies the tool is used to retrieve a node and its connections, but provides no explicit guidance on when to prefer this over other decision tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description says 'List decisions' implying a read-only operation, but annotation destructiveHint=true suggests mutation. This contradiction undermines transparency. No additional behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear verb, resource, and default. No wasted words. Front-loaded purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no description of return format or pagination. Contradiction with annotations creates confusion. For a list tool with 3 optional params, more context needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with descriptions (100% coverage). Description adds default behavior (active decisions) not explicitly in schema, but it's minimal. Baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'List', resource 'decisions in the local Decision Graph', and default behavior 'Defaults to active decisions', distinguishing from siblings like decision_get (single) or decision_add.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Indicates default behavior (active decisions) but no explicit guidance on when to use this vs alternatives like decision_get or decision_add. Usage is implied from the verb and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the scope of strategy areas but does not disclose additional behavioral traits like return format or pagination. This is adequate but not enhanced beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the purpose, the second lists coverage areas. No redundant information. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 params, no output schema, read-only), the description is reasonably complete. It covers the tool's domain and parameter context. Could benefit from mentioning output format, but not critical for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters described. The description lists strategy areas but does not add meaning beyond the schema's parameter descriptions (e.g., 'type' values). Per guidelines, baseline of 3 is appropriate when schema fully covers parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves business and monetization strategies, listing specific domains like monetization models, retention, etc. It is a clear verb+resource combination, but lacks explicit differentiation from similar sibling tools like 'get_metrics_framework'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'get_principles' or 'search_knowledge'. There are no when-to-use or when-not-to-use statements, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what annotations already provide ('readOnlyHint=true', 'destructiveHint=false'). It does not mention error handling, rate limits, or return behavior, leaving gaps for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, directly stating verb and resource without any redundant words. It is front-loaded and efficient, earning its place entirely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, high schema coverage, no output schema), the description adequately covers the core purpose. However, lacking output schema details means the agent is left guessing about the return structure, which slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the single parameter 'id', which is adequately described as 'Generation job ID.'. The description's mention of 'by ID' aligns with this but adds no extra meaning, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the resource ('Raven creative generation job') with the identifier method ('by ID'). It effectively conveys the tool's purpose, though it does not explicitly differentiate from sibling tools like 'list_generation_jobs'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., 'list_generation_jobs'), nor any exclusions or prerequisites. The agent must infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description confirms 'update' behavior. It adds that applied/rejected/superseded changes leave the pending set, which is useful. However, it does not detail what exactly is destroyed or the consequences of marking operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core functionality. It efficiently lists the three operations, though the structure could be clearer (e.g., separating modes). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the three main operations but lacks explanation of return values, domain-specific terms like 'durable grab change', and how the operations relate. With no output schema and moderate complexity, more completeness would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter (mark, batch, operation_id) already has descriptions. The tool description adds overall context but does not enhance parameter-level meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool can read or update a durable grab change, list legacy reorder operations, or request a unified batch. It identifies the resource and verb, distinguishing from siblings like get_grab_layers or move_grab_layer, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit when-to-use or when-not-to guidance. It does not mention alternatives or conditions for using this tool over siblings, leaving the agent to infer context. The multi-mode nature would benefit from clearer usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds no substantive behavioral details beyond the name and examples. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the purpose. The list of examples is somewhat long but not excessive. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two optional params, no output schema), the description covers the type of content but does not mention what the response contains (e.g., list of preset objects with details). Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters have descriptions), so baseline is 3. The description does not add any parameter info beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'Raven creative presets' and provides many example categories (product photoshoots, UGC ads, etc.), indicating the scope. However, it does not explicitly differentiate from sibling list tools like list_creative_models, missing a chance to clarify when to use this one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., list_creative_models). The description only lists categories, omitting context for when not to use it or what to do instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior; description adds that it reads from a local DESIGN.md file but does not disclose error handling or file format expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no unnecessary words; effectively communicates the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not specify return format or structure; adequate for a simple read tool but could be more explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions; the tool description does not add new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads component declarations and tokens from a local DESIGN.md file, but does not explicitly differentiate from sibling tools like read_design_md.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; no prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, consistent with 'update'. The description notes token modification while preserving the body, but lacks details on error handling, permission requirements, or side effects. Adequate but not thorough for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, highly efficient, conveys the core action and constraint without redundancy. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, nested objects, no output schema, and a destructive annotation, the description is too sparse. It doesn't explain what a 'token' is, the file format, or the effect of each operation, leaving context incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only 'path' has a top-level description). The description adds no parameter context, leaving set/remove/rename operations unexplained. Does not compensate for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'update', the resource 'DESIGN.md', and adds precision with 'surgically' and 'preserving the Markdown body', distinguishing it from read or init tools. The title reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like read_design_md or init_design_md. No mention of prerequisites or when not to use it, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate destructiveHint: true, meaning the tool modifies state. However, the description does not explain the exact effects, reversibility, or necessary permissions, which is needed for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded, but it is slightly vague in 'distinct scopes'. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description sufficiently explains the tool's purpose. However, it could provide more context about the overall system and the tool's role in decision management.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all four parameters with 100% coverage. The description adds context like 'existing' and 'narrowed' but does not significantly augment the schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (narrow), the resource (two decisions), and the desired outcome (both remain active). It distinguishes the tool from sibling tools like decision_supersede or decision_commit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when two decisions have overlapping scopes, but it does not explicitly state when not to use it or provide alternatives among the many sibling decision tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, so the description need not reiterate destructiveness. It adds context about starting a local server and injecting an overlay, but does not explain side effects like cleanup or what precisely is destroyed, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. First sentence states purpose, second explains modes. Well front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 conditional parameters, a destructive annotation, and no output schema. The description does not explain what 'grab bridge' means, the role parameter difference, or what the return value is (e.g., session ID). This leaves significant gaps for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds minimal value beyond the schema. It reinforces the relationship between proxy_target and the preferred mode, but does not provide new syntax or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'start' and names the resource 'Raven grab bridge on loopback'. It distinguishes from sibling tools like stop_grab_session (stop) and get_grabbed_elements (retrieve). However, the jargon 'Raven grab bridge' may be unclear to some agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states proxy mode is the 'preferred zero-paste path' and explains the two modes (proxy vs manual script tag), giving usage context. However, it does not explicitly compare to alternatives like stop_grab_session or mention when to choose this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the concept of creating a composite but does not clarify persistence (is the composite saved or ephemeral?), nor does it describe the output format or any side effects beyond mixing tokens. With annotations covering safety, the description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and an illustrative example. Every word serves a purpose. No redundant or missing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given moderate tool complexity (2 params, one array of objects), no output schema, and annotations covering safety, the description adequately hints at the result via example but does not explicitly state return value or behavior (e.g., 'returns a composite token set'). Could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents both parameters. The description provides an example (Linear's colors + Stripe's typography) that illustrates usage but does not add semantic detail beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('mix tokens') and resource ('design systems') to create a custom composite, with a concrete example. It clearly distinguishes from sibling tools like list_design_systems or get_design_system.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives such as get_design_system or generate_design_system. The description implies composition of multiple systems but does not state prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description indicates a write operation ('Save'), aligning with destructiveHint=true. However, it does not disclose side effects like overwriting existing configuration or validation of file existence. Annotations already indicate destructiveness, so description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single sentence that directly states the purpose with no unnecessary words. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple configuration tool, but lacks details on return value, persistence, or effects on other tools like inventory_design_system. Given 5 parameters and no output schema, more context would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and baseline is 3. The description does not add any parameter-specific information; it only references 'local DESIGN.md file' but ignores other parameters like project_dir, source_kind (const), aliases, etc.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Save' and resource 'local DESIGN.md file' with purpose 'for design-system inventory and comparison'. It distinguishes from sibling tools like read_design_md or init_design_md.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites, such as existence of the DESIGN.md file or prior initialization. Lacks explicit 'use when' context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims to 'generate' which implies a write operation, but annotations declare readOnlyHint=true, creating a contradiction. No additional behavioral traits (e.g., side effects, auth requirements) are disclosed beyond the conflicting annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler, front-loading the main purpose and enumerating key features efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the generation purpose and export formats but lacks details on return value (e.g., does it return the generated system or a URL?) and does not clarify the contradictory readOnlyHint. Adequate but incomplete for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaningful context: brand_color auto-generates a palette, style influences multiple aspects, and format options are listed. This adds value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a complete custom design system with full token set, listing export formats and customization options. It distinguishes itself from sibling tools like get_design_system or list_design_systems by focusing on generation rather than retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a complete design system is needed, but does not explicitly state when to use this tool versus alternatives (e.g., for partial updates or specific component generation). No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds key context that Raven makes no model or network call, which is beyond annotations. However, does not explain the 'destructive' nature indicated in annotations; 'store' implies creation, not destruction, leading to potential ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with no wasted words. Front-loaded with action and output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately describes the core function but lacks details on return value structure, next steps, or relationship with sibling tools like ingest_transcript_results. Given no output schema, more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds no additional information about parameters, thus baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it stores a transcript source and returns an extraction prompt, with explicit verb and resource. Distinguishes from sibling tools like ingest_transcript_results by specifying the immediate output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. Does not mention prerequisites, related tools, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, establishing it as a safe read operation. The description adds no additional behavioral context (e.g., scope of 'local', rate limits), but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is appropriately front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless list tool, the description adequately states what it does. It does not describe return format, but with no output schema and low complexity, the information is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the input schema provides full coverage. The description does not need to add parameter details. Per guidelines, baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'local Raven creative brand profiles' using the verb 'List'. It is distinguishable from sibling listing tools by specifying 'brand profiles' and 'local', though the exact meaning of 'local' is not elaborated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives like 'list_creative_models' or 'get_brand_profile'. There is no mention of prerequisites, filters, or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims the tool does not mutate the live page ('without mutating'), but the annotations set destructiveHint=true, implying the operation is destructive. This is a direct contradiction, severely undermining trust in the description's accuracy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) and well-structured, front-loading the primary operations and important caveats. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (17 parameters, 8 required, no output schema), the description covers the core behavior and key distinctions but omits details on many parameters like measuredRects, orderedSelectors, and approximate, making it incomplete for fully informed usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 24% schema description coverage, the description adds some parameter meaning (e.g., toParentSelector for reparent, parentSelector for reorder, role rejected). However, many critical parameters (fromSelector, baselineOrder, measuredRects, etc.) remain unexplained, leaving gaps for a 17-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queues a same-page layer reorder or reparent intent without mutating the live page. It specifies the two operations (reorder vs reparent) and distinguishes their use cases, making the purpose unambiguous and distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use reorder (single parentSelector) vs reparent (toParentSelector) and notes that shadow-root and iframe boundaries are out of scope. It does not explicitly name alternative tools, but the sibling list shows no other move-layer tool, so context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, and the description does not contradict them. It adds valuable behavioral context: the tool runs adversarial queries, returns specific verdicts, and catches shape-valid but wrong responses. This enhances transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the core action. However, it could be more structured by briefly covering key parameters or output, but overall it is efficient without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex schema (nested objects) and no output schema, the description is incomplete. It does not explain the verdict meanings, how to interpret results, or provide any error-handling context. Missing details about expected_shape_schema structure or query limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not explain the parameters (endpoint_url, queries, expected_shape_schema) beyond a high-level mention. The complex nested objects (queries array, expected_shape_schema) lack any textual guidance on their structure or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is specific: it states the tool runs adversarial queries against a live endpoint and returns per-query verdicts (shape-valid, shape-invalid, confident-wrong, uncertain). It clearly distinguishes from siblings by focusing on catching shape-valid but wrong responses, a unique capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests using the tool for adversarial API testing but provides no explicit guidance on when to choose this tool over alternatives like audit_contract or audit_parity. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint. The description adds that it returns yes/no items, which is minimal extra context. No mention of error behavior, required scopes, or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences (19 words), no redundant information, and no repetition of structured fields. Slightly more detail on output could improve it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema, the description provides adequate but minimal context. It does not describe the structure of the checklist items or how many items to expect, leaving the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions. The tool description adds no additional meaning beyond the schema, meeting the baseline 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a pre-publish checklist for a specific UI type, using a specific verb and resource. It distinguishes from sibling audit tools by specifying it returns actionable yes/no items rather than performing an audit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for verifying a UI type before shipping, but does not explicitly state when to use this tool versus alternatives like audit_* tools, nor does it provide any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so additional transparency is minimal. The description adds context about the returned content categories but does not disclose behavior beyond what annotations imply (safe read operation).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently conveys the tool's purpose and content. It front-loads the key action ('get a brand's content design system') and enumerates components without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description partially compensates by listing the sections of the content design system. However, it does not specify the structure or format of the output, leaving the agent uncertain about what the response will look like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for both parameters. The description enhances understanding by listing example values for id and the full set of section options, adding meaning beyond the schema's enum list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a brand's content design system, listing specific components like voice attributes, tone shifts, vocabulary, grammar rules, content patterns, and inclusive language guidance. It distinguishes itself from siblings like get_content_principles or get_content_pattern by referencing the full system.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. Siblings like get_content_principles, get_content_pattern, and list_content_systems exist, but the description does not explain how this tool differs or when to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, making safety clear. The description adds that it returns templates but no further behavioral details (e.g., no mention of output format or pagination). This is adequate given 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the key purpose and lists specific templates. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter, good schema coverage, and clear annotations, the description is largely sufficient. It could mention the default behavior (full stage) but the schema already covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the stage parameter with enum values and a description. The tool description lists template types but does not explicitly map them to stages. Since schema coverage is 100%, the description adds marginal value, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves D4D framework templates and lists the specific templates returned (customer problem statement, ideal state, etc.). This distinguishes it from sibling tools like get_principles or get_pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., other get_* tools). There is no mention of context or exclusions, so agents lack decision support for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that tokens are returned in specific formats, but does not disclose error behavior (e.g., invalid ID) or any rate limits. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the core action, second expands on return types. No unnecessary words. Front-loaded with the most critical information. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain the return structure. It lists token categories but does not specify the response format (e.g., JSON object structure). However, the detail about formats partially compensates, making the tool usable for an agent. Slightly incomplete but mostly adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 minimal new meaning beyond the schema, grouping the token categories and noting the default format ('dtcg'). This is helpful but does not significantly surpass what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'design tokens for a specific design system'. It lists the specific categories of tokens returned and the available output formats, making the tool's purpose highly specific and distinguishable from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Siblings include list_design_systems (for listing systems) and other get tools, but the description does not help the agent decide. No mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool reads without deleting, contradicting the annotations which set destructiveHint: true and readOnlyHint: false. This is a serious inconsistency that misleads about tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. The first sentence front-loads the core purpose, and the second provides essential context about the batchCommit signal. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema (1 optional param), no output schema, and the presence of annotations, the description covers the tool's purpose and key concept. Minor gap: no mention of return format or timeout expiration behavior, but still sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes timeout_ms as an optional integer. The description adds the phrase 'optionally waiting up to timeout_ms', clarifying the parameter's role beyond the schema. With 100% schema coverage, this adds meaningful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Read' and the resource 'newly sent grab selections', clearly distinguishing the tool from siblings like start_grab_session and get_grab_layers. It explains the action precisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (reading grab selections without deletion) but does not explicitly state when to use this tool versus alternatives or provide exclusions. No comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds context about the catalog being provider-agnostic and containing capability slots, but does not disclose additional behavioral traits like pagination or output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, clear sentences with no redundancy. Every phrase adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes the catalog contents and usage context adequately. No output schema, but for a simple listing tool with two optional filters, the description sufficiently informs the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameter descriptions. Description does not add new information about the two parameters (capability, media_type) beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Browse' and resource 'creative model catalog', clearly stating the tool lists capability slots for media types. While distinct from siblings like list_creative_presets or list_generation_jobs, it does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions need for a configured RAVEN_CREATIVE_RUNNER, providing some context, but no when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that this is a 'ledger' that evolves over time, hinting at its historical nature. No details on pagination, ordering, or limitations, but the transparency is adequate given annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that states the action, resource, filters, and contextual role. No redundant words or fluff. It earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 3 parameters, no output schema, and clear annotations, the description explains what it lists and the filtering options. It could mention the return format or ordering, but it is largely complete and leaves no major ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all three parameters. The description reinforces 'optionally filtered by project or dimension', which mirrors the schema but does not add new meaning. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'taste/direction/design decisions' for a profile, uses a specific verb ('List'), and references the companion tool 'record_taste_decision' for distinction. It also provides context ('the ledger that evolves the kickoff interview') that solidifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'decision_get' or 'decision_list'. The only reference is to 'record_taste_decision', which is the creation counterpart, not a sibling listing tool. The description lacks when-to-use or when-not-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint=true, which aligns with the description's mention of optionally creating draft generation jobs. However, the description does not elaborate on side effects like state changes, persistence, or reversibility, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action. No fluff or repetition. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description does not explain what the tool returns (e.g., campaign plan, job IDs). With 10 parameters and a planning purpose, more context on the response would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds a list of example workflows but no detailed parameter semantics beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool plans a multi-asset creative campaign and optionally creates draft generation jobs, using specific verbs and resource. It lists example workflows (product photos, UGC/video ads, etc.), distinguishing it from sibling tools that focus on specific audits or generation tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The description mentions 'Higgsfield-like workflows' but does not compare with alternatives or state prerequisites. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, and description is consistent. However, description does not add further behavioral context such as whether evidence replaces or appends, or any 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words, front-loads key information. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters and no output schema, the description is minimal. It does not explain return behavior or constraints beyond schema, but the schema is self-documenting. Adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description does not need to add parameter details. It adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('attach') and resource ('quantitative or qualitative evidence to an existing decision'), distinguishing it from sibling tools like decision_add (create) or decision_get (retrieve).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage when evidence needs to be recorded for an existing decision, but does not explicitly state when to use vs alternatives or provide exclusions, leaving the agent to infer context from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds value beyond annotations by specifying preservation of nodes and lineage. Annotations already mark destructiveHint: true; description clarifies that nodes are not deleted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, direct, no unnecessary words. Front-loaded with action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks explanation of output/return value. Simple tool with 2 params, but no mention of what happens after superseding (e.g., response, side effects).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. Description adds no additional semantic value for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Explicitly supersede one decision with another while preserving both nodes and their lineage.' It clearly identifies the action and distinguishes from sibling tools like decision_add and decision_commit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives. Does not mention any prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context by specifying the returned content (do's, don'ts, evidence, checklists) and listing supported pattern types, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that communicates the core purpose and enumerates pattern types. It is front-loaded but slightly lengthy due to the enumeration. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the return content (do's, don'ts, evidence, checklists) and covers the purpose and supported pattern types. Without an output schema, this is sufficient. Missing details like pagination or result limits, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive text for each parameter. The description lists pattern types but does not add significant new meaning beyond the schema's enum definitions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves proven UI/UX patterns for a specific design type, listing many pattern types. It uses a specific verb ('Get') and resource, distinguishing it from sibling tools like get_principles or get_business_strategy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It lists pattern types but does not explain context or exclusions. Sibling tools include many other 'get' tools, so usage guidance is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. Description adds no further behavioral context like return format or limitations beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loaded with verb and resource. Highly concise and effectively structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema provided; description does not mention pagination, ordering, or response structure. For a list tool with 3 optional parameters, it is adequate but fails to fully specify behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters (limit, status, media_type). Description adds no extra meaning beyond what schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List local Raven creative generation jobs' which specifies verb (list) and resource (generation jobs), distinguishing it from sibling tools like get_generation_job or create_generation_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., get_generation_job for a single job). Context implies listing, but lacks exclusion or comparison statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds output details (counts, timestamps) but does not disclose potential limitations like sorting or data scope beyond 'locally stored'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action 'List', no redundant words. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must explain the return value. It mentions key fields but is not exhaustive (e.g., profile names, IDs are not mentioned). Adequate for a simple list tool, but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100%. The description adds context about returned fields, which helps the agent understand what the list contains even though no parameter details are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists taste profiles and includes key information (rule/corpus counts, timestamps). It distinguishes from siblings like get_taste_profile (single) and create_taste_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as get_taste_profile or list_taste_decisions. The description does not provide selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description adds no new behavioral traits. It does not disclose search behavior like pagination, result limits, or algorithm, offering minimal additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, with no extraneous information. It is front-loaded with the purpose and usage context, making it efficiently scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 params, no output schema), the description is adequate but lacks details about return format or pagination. It covers purpose and usage but leaves some behavioral context unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description does not add any extra meaning beyond the schema's parameter descriptions; it merely restates the search scope.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches across design principles, UI patterns, and business strategies, distinguishing it from sibling tools that retrieve specific categories. The verb 'Search' and resource scope are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using the tool when you need specific guidance or don't know which category to look in, providing clear context. However, it does not explicitly mention when not to use it or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true; description adds context about local storage location and the set of fields stored, no contradiction detected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence conveying purpose and storage location; concise and front-loaded with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains what the tool does and stores, but lacks details on return values, id auto-generation behavior (partially in schema), and update semantics (e.g., overwrites existing if id matches).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline of 3 applies. Description summarizes stored fields (colors, fonts, etc.) but does not add new meaning beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create or update a local brand profile' with specific verb and resource, and distinguishes from sibling tools like get_brand_profile and create_character_profile by noting local storage under ~/.raven/creative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for creating or updating brand profiles but lacks explicit when-to-use guidance or alternatives among siblings such as get_brand_profile or list_brand_profiles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it returns results but omits behavioral traits like processing cost or state changes. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. Every word adds value. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters (all optional) and no output schema, the description and schema cover the essentials. It could mention that it works on textual design descriptions, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters adequately. The description adds no additional semantic meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it evaluates a design description against UX principles and returns relevant principles, violations, and suggestions. This distinguishes it from sibling audit tools that focus on specific aspects (e.g., audit_contrast, audit_layout).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool's function but provides no guidance on when to use it versus alternatives like audit_page or get_principles. Agents must infer its scope from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, destructiveHint=false, which the description aligns with. The description adds context that roles and allowedTokens are advisory metadata only, not enforced, which provides behavioral nuance beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence states the action and source, the second clarifies the semantics of the result. Information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool does and the nature of the returned data. However, it does not mention handling of missing grab sessions or invalid pages. Given the read-only nature and annotations, this is acceptable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with clear parameter description for 'page'. The description does not add parameter info beyond what the schema provides, meeting baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads page-scoped template slots from DESIGN.md and merges overlay validation. The verb 'Read' and specific resource 'page-scoped template slots' are precise. It distinguishes from siblings like set_template_slot or list_templates by focusing on reading for a single page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as list_templates or set_template_slot. The description does not mention prerequisites, when-not-to-use, or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=true. The description adds context about the initialization sources but does not clarify whether the tool overwrites an existing file or fails. Given the destructiveHint annotation, the description could be more explicit about the overwriting behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence of 18 words. It front-loads the action and lists the sources efficiently, with no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and no output schema, the description covers the core functionality and sources. It is mostly complete, but could be enhanced by specifying whether the tool overwrites an existing file, especially given the destructiveHint annotation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The tool description merely repeats the source options and path purpose without adding new meaning or usage details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool initializes a DESIGN.md file from three specific sources: a stored Raven token system, a getdesign.md starter slug, or a blank template. The verb 'Initialize' and the listed sources make the purpose concrete and distinguish it from siblings like read_design_md or update_design_md.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when initializing a DESIGN.md from given sources) but does not provide explicit guidance on alternatives or when not to use it. For example, it does not mention that one could use other tools for reading or updating an existing DESIGN.md.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark destructiveHint=true, and the description adds that imported history is review-only, partially clarifying the nature of the operation. However, it does not detail what side effects occur (e.g., writes to a temporary store) or explain the behavior beyond this hint. With annotations providing a baseline, the description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It is front-loaded with the core action and includes a key workflow detail, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no output schema, the description covers the purpose and a usage hint but lacks details on return values (what form do extraction prompts take?), prerequisites (must have a git repo), and what 'review-only' means in practice. Given the complexity, more context would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters with descriptions, defaults, and constraints. The tool description adds no additional meaning beyond what is in the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool mines local git history and decision-bearing Markdown into provenance-tagged extraction prompts. It uses a specific verb ('mine') and resource, and implies a unique function compared to siblings like decision_add and decision_commit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides workflow context by noting that imported history remains review-only until decision_commit, helping agents understand when to use this tool (bulk import) versus manual addition. However, it does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the qualifier 'local', suggesting a scope that is not evident from annotations alone, enhancing transparency. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 9 words, front-loaded with the action and resource. Every word is necessary and no verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description is adequate for a simple read operation with one parameter and good annotations, it does not specify the return format or content of the brand profile. Without an output schema, this information would help agents understand what data they receive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with description for 'id' as 'Brand profile ID.' The description only restates 'by ID', adding no new semantic value. Baseline of 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'local Raven creative brand profile', with the mechanism 'by ID'. This differentiates it from sibling tools like list_brand_profiles (list) and create_brand_profile (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific ID, but does not explicitly guide when to use this tool over alternatives like list_brand_profiles or get_brand_system. No when-not or context clues are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds moderate value by specifying return structure (do's/don'ts, examples, evidence, checklist). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads purpose and concisely lists return components. No filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one parameter, full schema coverage, and no output schema, the description adequately explains what the tool returns (structure of output). It is complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with a clear enum and description. The description briefly repeats the type values but does not add new semantic meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves content design patterns (copy recipes) for specific types like error messages, empty-state copy, notifications, and form validation. It distinguishes from sibling tools like get_principles or get_pattern by focusing on content-specific patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by listing what it returns, but does not explicitly state when to use it over alternatives. No exclusions or comparisons to sibling tools are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it lists 'components and provenance', but no additional behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and scope, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description is complete: it specifies what is listed and the target baseline.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'baseline', which has a const value. Description merely restates the default, adding no extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'list' and resource 'components and provenance' within the specific 'Raven canonical baseline'. This differentiates it from siblings like 'list_design_systems' and 'get_design_system'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context ('Raven canonical baseline') but does not explicitly state when to use this tool over alternatives or mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and destructiveHint, covering safety. The description adds no further behavioral context (e.g., pagination, limits, result format).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb 'Browse', no wasted words. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not specify what is returned (e.g., full objects vs. summaries). Adequate for a simple list tool but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description's parameter details (categories) duplicate the schema. No additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists design systems for tokens, with filtering options. It distinguishes from siblings like get_design_system (retrieving specific) and list_design_system_components (listing components).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions when to use it (browsing/filtering design systems) but does not explicitly exclude alternatives like get_design_system for specific systems.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true. The description adds value by clarifying it's a 'transparent heuristic, not a proprietary prediction model', explaining the nature of the scoring logic. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that efficiently convey purpose and nature. No fluff; each sentence is essential and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output format description (no output schema). While purpose is clear, users may not know what the tool returns (e.g., scores, feedback). Adequate for a simple scoring tool but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description connects parameters (channel, audience) to scoring dimensions (channel fit, audience fit), adding meaning beyond schema descriptions. It does not detail every parameter but links them contextually.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool scores creative content (prompt, script, ad concept) across seven specific dimensions. It distinguishes itself from sibling tools like 'score_page' by specifying creative evaluation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., audit tools). The description implies usage for creative evaluation but does not provide context for exclusion or selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, and destructiveHint. The description adds behavioral detail about surface detection and fan-out logic. No contradictions. The description does not explicitly state return format or side effects beyond what annotations convey, but that is acceptable given 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences. The first sentence is somewhat long but effectively communicates key behaviors. It uses bold and em dash for emphasis. Could be slightly more concise, but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no output schema, no return value description), the description provides an adequate high-level overview. However, it lacks details on what the tool returns (e.g., list of findings, results format), which would help an agent understand the tool's full output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds moderate value by noting that 'project' is for taste binding and 'intent' for optional focus. This helps parameter understanding but is not extensive; most meaning is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs all applicable Raven audits for a target, includes surface detection and fan-out behavior. It also explicitly tells the agent to use this instead of choosing individual audit_* tools, effectively distinguishing it from the large sibling set of specific audit tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this instead of choosing individual audit_* tools,' providing clear guidance on when to use this tool vs. siblings. It also mentions passing 'project' for taste binding. However, it does not explicitly state when not to use it or list alternative specific audit tools for narrow use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, matching the description's read behavior. The description adds significant behavioral context beyond annotations: it details specific checks (e.g., NS*UsageDescription contradictions, ATS exemptions, secrets in bundle) and the optional input combinations that trigger different analyses. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with the main purpose and then listing specific checks. Every sentence adds value, and it avoids unnecessary repetition. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple input combinations, various checks), the description covers the main functionality and references the return shape being the same as audit_page. However, it does not describe the output structure in detail, which might be needed since there is no output schema. Still, it is fairly complete for an experienced user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 5 parameters have descriptions). The description adds context by explaining the purpose of each parameter (e.g., source enables code-vs-declaration checks, app_json for Expo, info_plist for native), but the schema already provides adequate descriptions. Baseline of 3 is appropriate as the description adds marginal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool audits iOS/Expo app privacy posture for App Review and user trust, with a specific verb ('Audit'), resource ('iOS/React Native/Expo app privacy'), and scope (reading Info.plist or app.json, plus optional files). It lists concrete flags it checks (missing descriptions, contradictions, etc.), differentiating it from sibling audit tools like audit_ios_a11y or audit_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to audit privacy posture) and mentions the return shape is the same as audit_page, but does not provide explicit guidance on when not to use it or alternatives among siblings. The context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive action. Description adds context that actual identity training is external and only reference data is stored locally, which is beyond annotation signals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. Front-loaded with purpose and immediately clarifies scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main behavioral context (local storage, no training), but lacks return value description since no output schema. Minor gap for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters have schema descriptions (100% coverage), so baseline 3. Description does not add significant extra meaning beyond restating context like 'reference asset IDs'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'create', resource 'local character/identity reference profile', and purpose 'for consistent image or video generation'. Distinguishes from sibling tools by noting it is local and only stores references, not actual training.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage scenario (consistent generation), but no explicit when-to-use or when-not-to-use vs alternatives like create_brand_profile or create_generation_job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, so the agent knows it's a write operation. The description adds context about the return payload (brand-aware provider payload) and conditional submission behavior (if execute=true and runner configured), which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and every sentence adds value. No redundant or extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 15 parameters (2 required) and no output schema, the description covers the main purpose, return payload, and conditional execution. It provides sufficient context for an agent to understand the tool's role, though it could benefit from clarifying how it differs from other creative tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 15 parameters are already well-described in the schema. The tool description mentions media types and media_type parameter but adds no new semantic information beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a Raven creative generation job for specific media types (image, video, 3D, audio, campaign, analysis) and mentions returning a brand-aware provider payload and conditional submission. This distinguishes it from sibling tools like list_generation_jobs or get_generation_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creative generation but does not explicitly state when to use this tool versus alternatives like plan_creative_campaign or score_creative. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds clarity that it is non-mutating and that permissions are advisory-only metadata, providing context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no unnecessary words. Front-loaded with the core purpose, then a clarifying statement about permissions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one optional parameter and no output schema, the description covers the key context (snapshot, active session, permission nature). Could mention the return format or structure but not strictly necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for the 'page' parameter. The description text does not add significant meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it reads the latest non-mutating layer-tree snapshot from an active grab session. Differentiates from sibling tools like 'get_grabbed_elements' and 'move_grab_layer' by specifying the snapshot nature and read-only context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the permission labeling behavior but does not explicitly state when to use this tool versus alternatives like 'get_grabbed_elements' or 'search_knowledge'. No when-to-use or when-not-to-use guidance beyond the read-only nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that the tool returns 'usability heuristics, laws of UX, Gestalt principles, etc.' but does not disclose any additional behavioral traits like rate limits, authentication needs, or side effects. Since the annotations cover the safety profile, the description does not need to repeat that, but it also does not enrich behavioral understanding beyond what is already provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first clearly states the purpose, and the second lists the categories of principles returned. Every sentence is necessary and adds value. There is no fluff or redundancy, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity with four parameters and no output schema, the description is mostly complete. It explains what categories of principles are returned and that they are matched to the context. However, it does not describe the structure of the output (e.g., whether it returns a list or a single principle, how results are ranked), which could be helpful for an agent to know how to use the results. This minor gap prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions and enums where applicable. The tool description does not add new meaning beyond the schema; it restates the purpose of the 'context' parameter indirectly by saying 'matched to what you're designing.' With full schema coverage, the baseline is 3, and the description does not provide additional semantic value to justify a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get design principles relevant to a UI context.' It specificies the verb 'Get', the resource 'design principles', and the context 'relevant to a UI context.' This distinguishes it from sibling tools like 'get_pattern' or 'get_business_strategy' which focus on different types of content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool—when designing a UI and needing relevant principles. However, it does not explicitly state when not to use it or mention alternative tools, such as 'get_pattern' for patterns or 'get_brand_principles' for brand-specific guidance. The absence of exclusions slightly reduces the score from a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description adds value by specifying the content (brand voice and tone guides from real companies) and the filtering capabilities. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the main action and includes concrete examples. Every word adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, two optional parameters, and no output schema, the description adequately sets expectations. It could mention the return format (e.g., list of names/IDs), but the presence of a sibling get tool implies the list yields identifying information. Overall sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description reiterates the filtering options but doesn't add significant new semantics beyond what the schema provides. This meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to browse available content design systems, naming specific real-world examples (Mailchimp, GOV.UK, etc.), and mentions filtering by category or search. This distinguishes it from sibling tools like get_content_system, which retrieves a single system.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use—when you want to browse or find a content design system—but does not explicitly contrast with sibling tools (e.g., when to use get_content_system instead). There is no guidance on when not to use it, leaving the agent to infer from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds context by stating no files are written, the tool re-verifies hypothetical polished lines, and leaves judgment-heavy findings in manual. This provides meaningful behavioral transparency beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and each sentence adds specific value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 3 parameters, the description covers the tool's purpose, side effects, and return value (unified patch). It lacks explicit guidance on when to use versus alternatives, but is otherwise complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters well. The main description restates the diff parameter and mentions project/design_md, but adds little new semantics beyond 'without writing files' for context. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reviews added UI-code lines and proposes deterministic DESIGN.md token substitutions without writing files. It distinguishes from siblings like review_diff by specifying the design token substitution focus and the requirement for the caller to apply the patch separately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly provide usage guidelines or mention when to use this tool versus alternatives like review_diff or evaluate_design. It states the output is a patch to be applied separately, but lacks contextual guidance on appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true (mutation), so the description's statement of registration confirms behavior but adds no new insights about side effects, permissions, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that front-load the core purpose and usage, containing no unnecessary words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple registration tool with a destructive hint and no output schema, the description sufficiently explains purpose and when to call, though it could mention the creation of a record more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully describes both parameters (name optional, email required). The description adds no extra semantic meaning beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Register your email') and the resource ('to receive design updates and provide feedback to the Raven creator'), and distinguishes from sibling tools by specifying a unique registration function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context ('Call this when a user wants to register, give feedback, or connect with the Raven team'), but does not mention when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is clear. The description adds value by specifying the exact outputs (frontmatter, body, token index), which goes beyond the annotations. No contradictory or missing behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that front-loads the verb and resource. Every phrase serves a purpose with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description adequately covers what the tool does and returns. It omits error handling or edge cases, but the scope is narrow enough that missing details are not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single required parameter 'path' with description 'Path to DESIGN.md'. The tool description does not add additional semantic meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it parses a DESIGN.md file and returns specific components (frontmatter, body, token index). The verb 'Parse' and resource 'DESIGN.md' are precise, and it distinguishes from sibling tools by focusing on a specific file type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives. While the name implies it's for reading DESIGN.md files, there is no mention of when not to use it or which sibling tool might be more appropriate for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, and the description adds that it clears queued selections, providing additional behavioral context beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently conveys the action and effect with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description adequately explains the action. However, it could mention potential side effects like idempotency or behavior when no session exists, but it's largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema description coverage is 100%. The description adds no extra parameter info, which is acceptable since there are none. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stops a 'grab bridge' and clears queued selections. The verb 'stop' and resource 'grab bridge' are specific, and it distinguishes from the sibling tool 'start_grab_session'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as 'start_grab_session' or 'get_grabbed_elements'. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds rich behavioral details: it runs headless, is deterministic, uses cited principles, and flags waived findings with waived_by_taste:true. This goes beyond the annotations significantly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and front-loads the core purpose, but is presented as a single lengthy paragraph. Breaking it into bullet points or sections would improve readability and conciseness for an AI agent parsing the definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, nested objects, no output schema), the description adequately covers input variations, behavioral aspects, output characteristics (citation, waiver flag), and relations to sibling tools like audit_layout and bind_taste_surface. It provides sufficient context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema covers 100% of parameters with descriptions, the tool description adds crucial context: how url/html/elements are processed, that elements+viewport enable geometry rules, and how project/profile interact with taste binding. This enriches the agent's understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run Raven's deterministic detector engine over a page — no LLM, pure measurement.' It specifies the verb 'run' and resource 'detector engine over a page', and distinguishes from siblings by emphasizing deterministic, rule-based scanning without LLM, contrasting with LLM-based evaluation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides usage context by listing acceptable inputs (html, url, pre-measured elements+viewport) and mentions optional parameters (project, profile, surface). However, it lacks explicit guidance on when to prefer this tool over sibling audit tools like audit_layout or audit_consistency, and does not state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false; description adds details on checks performed (e.g., contrast, tap targets), consistent and adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with verb and checks. No fluff, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Good overview of input and checks, but lacks details on output format and specifics of parameters like dynamicTypeClipped. No output schema, so description could clarify return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description partially maps to schema: mentions elements and viewport structure but omits 'options' (minTarget). With 0% schema description coverage, description adds some but incomplete coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it scores iOS accessibility snapshots, listing specific checks (missing labels, tap targets, contrast, Dynamic Type, reading order). Distinguishes from siblings like audit_ios_screen by being snapshot-specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for use with AccessibilitySnapshot harness, but does not explicitly mention when not to use or alternatives. Implicitly clear from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, and destructiveHint. The description adds significant behavioral details: launches headless Chromium for URL, renders DOM, handles interactions, scroll settlement, and adversarial verification. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthier than minimal but front-loaded with core purpose and check list. It avoids redundancy with schema and effectively uses structure. Could trim some enumeration of checks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, nested objects, no output schema), the description covers return format, parameter behaviors, and edge cases (e.g., blank-section false positives). It fully equips an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 89%, so most parameters already have schema descriptions. However, the description adds valuable context for key parameters: containerMaxWidth's token-aware behavior, interactions' dynamic state capture, scroll_settle's false positive prevention, and adversarial_verify's confirmation logic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it audits HTML/CSS against Raven's design quality standards, listing specific checks. It distinguishes from siblings implicitly by focusing on page-level design standards, but does not explicitly contrast with other audit tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like 'audit' or other audit_* siblings. The only usage hint is for the containerMaxWidth parameter. No when-not-to-use or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral context: what it flags, what it rewards, and that source concatenation occurs. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed yet concise, front-loading the purpose and listing checks. Each sentence adds value, though it could be slightly more structured for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of audit checks, the description is thorough: covers what is checked, ignored, and return format (pass/fail with fix instructions). Without an output schema, it sufficiently describes outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 5 parameters. The description adds context for how parameters are used (e.g., accent_color_contents verification) but does not provide deeper semantics beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool audits SwiftUI source against Apple's HIG, lists specific checks (fonts, colors, tap targets, spacing), and distinguishes itself by being iOS-native only, differentiating from sibling tools like audit_ios_a11y or audit_ios_screen.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for auditing SwiftUI HIG compliance and explicitly excludes web/CSS rules, providing clear context. However, it does not name specific alternatives or state when not to use this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds that it returns structure and examples, but does not disclose additional behavioral traits beyond annotations. With annotations covering the safety profile, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (2-3 sentences) and front-loaded with the core purpose. Every sentence adds value: identifies frameworks, states return contents, gives usage examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 optional parameters, no output schema), the description adequately covers what the tool does, what it returns, and when to use it. No gaps are evident for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both parameters (id and search). The description lists id values in text, but this largely duplicates the schema. The description does not add significant meaning beyond what the schema provides, baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a product-metrics framework, enumerates specific frameworks (HEART, AARRR, etc.), and describes what is returned (structure, when-to-use, pitfalls, examples). It effectively distinguishes from sibling tools like get_principles or get_business_strategy by focusing on metrics frameworks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage cues: 'Use when the user asks "how should we measure success?" or "what metrics should we track?"'. However, it does not mention when not to use this tool or suggest alternatives among siblings, which would improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that data is read from a local log file ($RAVEN_USAGE_LOG or ~/.raven/usage.jsonl) with no network fetch, providing useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, front-loading the main action. Minor redundancy in mentioning local log twice, but overall efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description lists the summary contents. For a read-only tool with one optional parameter and clear data source, it provides sufficient context for an agent to understand usage and boundaries.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the only parameter ('days'), with a clear description. The tool description mentions 'over the last N days' but does not add extra semantics beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: summarizing Raven usage over N days, detailing which tools are called, audit warnings, patterns, design systems, and brand style queries. The verb 'summarize' and specific content list provide clear action and scope, distinguishing it from sibling audit tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit triggers: 'Call this when the user asks what have I been building with Raven or what's Raven missing.' This guides invocation. It does not mention when not to use it or alternatives, but the purpose is narrow enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds that the tool stores metadata/URI rather than file bytes, which is a key behavioral trait. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The key action is front-loaded, and the upload comparison is a concise differentiator.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the purpose is clear, the description lacks details about return values (no output schema) and does not elaborate on parameter semantics or edge cases. Given the tool has nested objects and multiple parameters, more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add additional meaning beyond the schema definitions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'register' and resource 'creative asset', and distinguishes from upload by noting it stores metadata/URI not file bytes. This is specific and differentiates from the implied sibling tool 'upload'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use this tool (local-first analog of upload, for local or remote assets), but does not explicitly list when not to use it or name alternatives among the provided siblings. The contrast with upload is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive, and the description adds context that the update is batched and that roles (fixed/flexible) are cooperative advisory metadata (not enforced). This enriches behavioral understanding without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 22 words, front-loading the core action and then adding a clarifying note about roles. Every word earns its place; there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic operation but does not specify whether the call overwrites or appends slots, nor does it mention the return value (no output schema). Given the tool's moderate complexity (3 params, nested array), these omissions leave gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds important semantic nuance: it clarifies that the role enum values are 'display labels only, not enforced', which goes beyond the raw schema. Other parameters are adequately described in the schema, so the description adds marginal but valuable extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'persist' and the resource 'page-scoped template slots' in a specific context ('one batched DESIGN.md update'), making the tool's purpose distinct from siblings like get_page_template or update_design_md.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description implies this tool is for persisting template slots, it does not explicitly provide when to use it versus alternatives (e.g., when to use this over update_design_md) or when not to use it. No exclusion or prerequisite details are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe operation. The description adds valuable behavioral details: flags missing/inconsistent tokens, schemaVersion drift, prefix-ordering bugs, and outputs a 'BLOCK/PASS verdict', which enriches the agent's understanding beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines purpose with verb+resource, second adds specifics and verdict. No redundant words, efficient and front-loaded. Perfect conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description mentions the 'BLOCK/PASS verdict', which gives a basic idea of return. It sufficiently explains the tool's function and parameters. However, it lacks detail on the format of the verdict (e.g., if it includes specifics of failures). For a moderate-complexity tool with nested objects, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does by explaining that 'contract_spec' includes token list, field set, and schemaVersionPattern, and that 'file_paths' are source files. This adds meaning beyond the schema's raw field names, though it could be more explicit about parameter syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'verify' and clearly identifies the resource: wire contract across independent source files (iOS Swift, proxy JS, Android Kotlin). It also lists what it flags (missing tokens, schemaVersion drift, prefix-ordering bugs), distinguishing it from sibling audit tools like 'audit_api_contract' or 'audit_ios_a11y'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use case: when needing to verify wire contract consistency across platforms. However, it does not explicitly state when not to use it or mention alternative tools. The context is clear but lacks explicit guidance for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false. The description adds platform-specific scoring details (touch minima, semantic color treatment) and mentions that screenshot is for reference only. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that is dense but not overly long. It front-loads the purpose and then adds details. Some sentences are long, but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, the description explains the main behavior and platform differences. However, it omits mention of scroll_settle (boolean parameter) and does not explain profile/project parameters in the description (though schema covers them). Could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (86%), but the description adds value by explaining the behavior of platform (default ios, Android 48dp) and that screenshot is optional. It clarifies the expected use of certain parameters beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb ('Audit') and specifies the resource ('a rendered mobile screen (iOS or Android) from a view-hierarchy/accessibility snapshot'). It distinguishes from siblings by noting the return shape is the same as audit_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that calling with no arguments yields the expected snapshot shape, and that platform parameter changes scoring rules. It does not explicitly exclude alternatives or provide when-not-to-use, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint true and destructiveHint false, confirming no side effects. The description adds valuable behavioral context: what specific issues are reported (missing components, states, variants, token drift) and the output format (scored report with fix priorities), going beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the main action and packs detailed output information efficiently. Every word contributes meaning; no wasted space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately describes the return value (scored report with fix priorities). It covers the tool's functionality and input parameters (via schema). Minor gap: it does not explicitly state that all parameters are optional, but the schema conveys that. Overall complete for a read-only diff tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The description does not add significant new meaning for individual parameters; it provides overall context. Baseline of 3 is appropriate as the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Diff a project's declared design system'), the resource (DESIGN.md vs Raven canonical baseline), and the specific outputs (missing components, states, variants, token drift, scored report with priorities). It clearly distinguishes from sibling audit tools by specifying the baseline comparison aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for checking design system compliance against a baseline, but does not explicitly state when to use versus alternatives like 'audit' or 'evaluate_design'. No 'when not to use' guidance is provided, though the purpose is clear enough for an AI to infer typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and description adds return details (protocols, guidance, evidence, checklist). No contradictions; sufficient behavioral disclosure for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first lists contents, second states usage. No redundant or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 optional parameters, no output schema, and read-only annotations, the description adequately covers what the tool returns and when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both 'search' and 'category' parameters. Description reiterates categories but adds no new parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get research method details' and enumerates qualitative, quantitative, and usability methods. This specific verb-resource combination distinguishes it from sibling tools like 'get_principles' or 'get_pattern'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when the user is designing a study or asking how to measure something.' While it doesn't list exclusions, the context is clear and appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare `destructiveHint: true` (modifying state) and `readOnlyHint: false`. The description adds crucial context: 'Nothing is auto-confirmed', indicating the operation is safe in that it creates reviewable candidates without automatic confirmation. This adds transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundant words. The first sentence states the core action, the second adds a critical behavioral qualifier. Perfectly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and only two parameters, the description covers the primary purpose and a key behavioral trait (no auto-confirm). It does not detail return values or prerequisites (e.g., source_id must exist), but for a pipeline tool it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description adds minimal extra meaning beyond the schema, simply indicating the role of the extraction JSON as 'model-produced'. Baseline 3 is appropriate as the schema already documents adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb ('parse' and 'ingest') and the resource ('model-produced extraction JSON' into 'reviewable Decision Graph candidates'). It distinguishes from siblings like `ingest_transcript` by specifying the input is extraction JSON from a model, not raw transcript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: when a model produces extraction JSON that needs to be turned into reviewable candidates. However, it does not explicitly state when NOT to use the tool or mention alternatives like `ingest_transcript`. The context of siblings provides some implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable context about the output ('structured CI verdict with file/line findings and nearest-token suggestions'), which is beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence states action and output, the second gives usage guidance. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description provides a sufficient summary of the return value. It covers the main behavior but could be slightly more explicit about the verdict structure and default advisory mode. Still, it is complete enough for an agent to understand the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a detailed description. The tool description adds high-level purpose but does not enhance per-parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reviews UI-code lines in a unified diff against DESIGN.md tokens and design decisions, returning a structured CI verdict. This specific verb+resource combination distinguishes it from many sibling audit tools that focus on other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The explicit directive 'Agents should call this on every PR or diff that touches UI code before merge' provides clear when-to-use context. However, no alternative tools are mentioned for cases where the diff does not touch UI code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, non-destructive, and open-world. Description adds behavioral details: what the tool reports (selector, ratio, delta-to-pass) and that screenshot is for reference only. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, well-structured sentence front-loads the main action and packs output details efficiently. No extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Handles both input modes and describes output format (AA/AAA pass/fail, failing pairs) despite no output schema. Complete for a targeted audit tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The tool description reinforces the two modes but does not add significant new meaning beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it computes WCAG contrast ratios for text elements from a URL or dom_snapshot, reporting AA/AAA pass/fail and failing pairs. Distinguishes from sibling tools like audit_contract or audit_api_contract that address other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes two input modes (url or dom_snapshot) and mentions replacing manual computation. Provides context but no explicit when-not-to-use or alternatives beyond contrast fixing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, which align with the description's non-destructive read operation. The description adds context about requiring headless chromium and the return format, disclosing key behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: first the main action, then categorization, then return format, then requirement. Every sentence is informative with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently explains the output (table of fields) and prerequisites (headless chromium). Tool complexity is moderate, and the description covers all necessary context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by specifying default breakpoints (390, 768, 1440, 2160) and default viewport height (900), which are not in the schema. This aids agent in understanding defaults without guessing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's function: rendering a URL at multiple breakpoints and flagging elements hidden on mobile. It categorizes findings as 'likely-oversight' or 'intentional', providing clear differentiation from other audit tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly state when to use it versus alternatives like audit_page or audit_content. The context is implied by the tool's specific focus, but no direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and destructiveHint=false. The description adds specific behaviors: flags issues, rewards patterns, concatenates source, returns same shape as audit_page. No contradictions; adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: main purpose first, then list of checks, rewards, scope limitations. Slightly verbose but front-loaded and every sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (5 params, no output schema), description covers behavior thoroughly, including edge cases for color_scheme. References return shape via audit_page sibling, which is helpful but not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have schema descriptions (100% coverage). Description adds context: source concatenation, profile search behavior, project binding and note_assessments, color_scheme suppression of dark-mode check. Adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it audits React Native/Expo source against iOS and Android conventions, listing specific checks. It distinguishes from siblings by noting 'RN-native checks only' and referencing audit_ios_screen. Verb 'Audit' and resource 'React Native/Expo source' are precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for RN source auditing and explicitly excludes web/CSS or SwiftUI rules. It provides context for when not to use and mentions sibling tool audit_ios_screen. No explicit alternatives but clear scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds extensive behavioral details beyond annotations: includes deterministic detectors, delegated audits, design notes verification, verdict types, scoped rules, and fidelity findings. No contradiction with readOnlyHint or destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is excessively long and written as a single dense paragraph. It would benefit from bullet points or logical sections to improve AI agent parsing. Although front-loaded with purpose, overall structure is poor.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given tool complexity (8 parameters, multiple modes, design notes, scoped rules), the description covers all necessary context: mode behaviors, verdict logic, handling of missing data, and interaction with other taste tools. No output schema, but description adequately implies return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds deep context for each parameter, such as explaining how url mode handles headless rendering, how project resolves bindings, and how surface activates scoped rules. Significantly enriches schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool judges a target against a taste profile, with specific verb 'judge' and resource 'taste profile'. It distinguishes from sibling audit tools by focusing on taste/design fidelity and brand alignment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (e.g., need to judge design against taste profile) but does not provide explicit when-not-to-use guidance or compare to alternative sibling tools like audit_contrast or audit_layout.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, which the description does not contradict. The description adds behavioral context such as the return structure (scale, line_height, etc.) and the requirement for headless chromium in URL mode. It also explains that the tool emits a focused report, going beyond simple checks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the overall purpose, then bullet-pointing the three audit aspects, and concluding with the return fields and a note about headless chromium. It is informative without being overly verbose; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (three audit dimensions) and the absence of an output schema, the description adequately explains the return value (scale, line_height, weight_ladder, etc.) and the structure of findings. It also mentions the distinction from 'audit_page', providing sufficient context for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are described in the schema (100% coverage), but the description adds meaningful context: it explains that 'url' requires headless chromium and that 'nodes' are pre-collected text nodes for analysis without rendering. This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it audits the typographic scale of a rendered page or pre-collected snapshot, listing the three specific aspects (modular scale, line-height consistency, weight ladder). It explicitly distinguishes from the sibling tool 'audit_page' by noting it goes beyond pass/fail typography checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it mentions 'url mode requires headless chromium' and contrasts with 'audit_page' for simpler checks. It does not explicitly mention when not to use or list alternatives, but the guidance for when to use each mode is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, openWorldHint=true, destructiveHint=false. Description adds behavioral detail: headless Chromium rendering, sampling currentTime before/after play attempt. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose, usage paths, and unique value. Front-loaded with key information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no output schema, description covers necessary context: classification types, two usage modes, and practical application. Complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description need not add much. Description briefly mentions url and dom_snapshot but does not add significant meaning beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'audit' and resource 'video playback'. It explains the tool renders a page, observes video elements, and classifies them. It distinguishes itself from static audits by catching black/non-playing videos, a common defect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides two usage paths: URL rendering or pre-collected observations. It implies when to use (catch defects missed by static audits), but does not explicitly state when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true; description adds detail: local file persistence, merge behavior (template first, then explicit/markdown), and the 'overwrite' semantics. Warns about noise from inappropriate docs. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is lengthy with multiple paragraphs covering edge cases and warnings. While information-dense, it could be more concise. Front-loaded with primary purpose but drifts into detailed markdown parsing rules that might overwhelm.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers file location, merge logic, template behavior, and post-invocation step. Missing return value or error handling (e.g., invalid name, duplicate rule_id). Given no output schema, some behavioral context is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds substantial meaning: explains rules object fields in detail, markdown ingestion format with syntax examples, template enum semantics, and order of merging. Goes far beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it creates/overwrites a named taste profile with specific components (ruleset + precedent corpus). Distinguishes from sibling tools like get_taste_profile (read) and audit_taste (evaluate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance for passing rules, markdown, or template. Warns against using non-RULES-SHAPED docs. Recommends subsequent get_taste_interview call. Could explicitly contrast with get_taste_profile for when to read only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds context by specifying that the tool returns the 'complete supersession lineage' ordered 'oldest to newest,' providing valuable behavioral details beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 14 words, efficiently conveying the purpose and key details. No unnecessary words; information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and read-only. The description explains what is returned (complete supersession lineage ordered oldest to newest). Although there is no output schema, the description is sufficient given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'id'. The description adds meaningful context: 'Existing decision id anywhere in the supersession lineage.' This clarifies that the id can be any node in the lineage, not just the root, which is not obvious from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'the complete supersession lineage for a decision, ordered oldest to newest.' It uses a specific verb ('Return'), specifies the resource ('supersession lineage'), and includes ordering, distinguishing it from sibling tools like 'decision_get' or 'decision_list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives. It implies usage for retrieving history, but lacks explicit guidance on when to choose it over related tools like 'decision_get' or 'decision_list'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false, so the description adds value by detailing what is returned: full token set, style guide, implementation instructions, CSS/DTCG/guide formats. No contradictory behavior is described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no wasted words. Efficiently conveys all necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description adequately explains the return values (full token set, style guide, implementation instructions, CSS). Given no output schema, it provides sufficient completeness for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning beyond schema: it explains that the company param selects a brand and that format affects output (CSS, DTCG, guide). It also mentions defaults indirectly. This provides useful context beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a complete design system for a company's branding, with specific examples like Spotify and mention of 12 known systems. It distinguishes itself from siblings like 'get_design_system' or 'list_design_systems' by focusing on brand-specific design systems.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage in a conversational context ('Say 'Make me an app...'), but does not explicitly state when to use or not use this tool versus alternatives. It mentions matching against 12 known systems, but lacks guidance on when to prefer other tools like 'list_design_systems'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds value by listing example principles (clarity, active voice, etc.) and the filtering behavior. It does not contradict annotations and provides useful behavioral context beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two efficient sentences. It front-loads the core purpose and immediately explains filtering capability. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two optional parameters and no output schema, the description covers the necessary information: what it returns, how to filter, and example contexts. It is sufficiently complete to guide correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with descriptions for both 'format' and 'context' parameters. The description adds specific examples for context (e.g., 'error messages') and implies filtering, which enhances understanding beyond the schema. The format parameter is explained in the schema, and the description doesn't repeat it, so the added value is moderate but meaningful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'UX-writing principles' and can be filtered by writing context. The verb 'Get' and resource 'content principles' are specific and unambiguous. It distinguishes from siblings like 'get_principles' and 'get_content_pattern' by explicitly mentioning UX-writing context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains filtering by context and omitting to get all, but lacks explicit guidance on when NOT to use this tool versus alternatives like 'get_principles' or 'get_content_pattern'. It provides clear context for usage but no exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context about the content (14 points) and broader applicability, but no additional behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first identifies the resource, second provides usage guidance. No extraneous information, and every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with annotations, the description fully covers what the tool returns (the 14 points) and when to use it. No gaps remain given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description does not need to add parameter semantics. It correctly omits any, achieving the baseline score for this case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: 'the GOV.UK Service Standard — 14 points' and the action 'Get'. It distinguishes itself from sibling tools by noting its wide applicability as a checklist beyond government.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use: 'Use when the user asks how to evaluate a whole service.' While it does not mention when not to use or list alternatives, the context is clear and helpful for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so this is a write operation. The description adds context on how records affect future interviews and explains the signal strength of different source types. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and is fairly concise given the complexity. It could be slightly trimmed (e.g., the impact on interviews could be shorter), but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but for a write tool that's acceptable. The description thoroughly covers the purpose, parameters, and impact. Given 7 parameters and the tool's role in the system, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions, but the description adds extra meaning: dimension can be standard or new (and new ones become interview questions), source enum values are clarified, and 'user-corrected' is flagged as highest-signal. This goes beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'record' and resource 'taste, direction, or design decision', clearly distinguishing it from siblings like decision_add or decision_commit. It explains exactly what constitutes a decision and when to record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to record 'the MOMENT it is made' and contrasts with 'not just at interview time'. It also explains the downstream effect on get_taste_interview kickoff, but does not explicitly compare to alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, indicating safety. The description adds value by specifying 'Pure offline — no network or browser' and detailing the deterministic heuristics. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph dense with information, front-loading the purpose and then detailing heuristics and output. It is concise but could be slightly more structured (e.g., breaking heuristics into a list). Minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description thoroughly explains the return format: per-item verdict with matched principle ids, issues, rewrite suggestion, and an aggregate summary. It lists heuristics for each content type, making the tool fully understandable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed descriptions in the schema (e.g., for 'type' it says 'Content type — selects which heuristics apply'). The tool description adds context on item types and heuristics but does not significantly enhance parameter meanings beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool evaluates content items against UX-writing principles and heuristics, listing specific item types (headings, prose, CTAs, etc.) and the output per-item verdict. It also explicitly distinguishes itself from the sibling evaluate_design by contrasting their outputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('when you need per-item content verdicts') and when not to ('rather than the principle library'), naming the alternative evaluate_design. This helps the agent decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds context about the tool's operation: it checks named spatial relationships and generates per-relation statuses. It does not contradict annotations and provides useful behavioral detail beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no extraneous content. It front-loads the core purpose and immediately states required inputs, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested parameters and no output schema, the description covers the core function, input requirements, and output type. It could marginally improve by specifying the return format (e.g., a list of results), but the current level is sufficient for correct agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains the meaning of the three required parameters: 'ios+android {elements,viewport} snapshots' and 'checklist[]'. It also elaborates on the checklist's purpose and the spatial relationships, adding significant value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('compare') and resource ('iOS vs Android element snapshots'), explicitly naming the spatial relationships checked and the output types (match/mismatch/uncertain). It clearly distinguishes from sibling audit tools by focusing on cross-platform parity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what inputs to provide ('Provide ios+android {elements,viewport} snapshots and a checklist[]'), implying the tool is used for cross-platform layout drift detection. However, it does not explicitly exclude scenarios or mention alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively discloses behavioral details beyond annotations: it persists to a file (~/.raven/taste/<profile>.surfaces.json), performs upserts, carries forward omitted fields, refuses empty bindings, and generates consistency_warnings and build_hints. Even though annotations indicate destructiveHint=true, the description clarifies the mutation behavior (upsert) and safety mechanisms (carry-forward), aligning with and enriching the annotation signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long and packed with information, which is necessary given the tool's complexity (9 parameters, nested objects, multiple side effects). However, it lacks structural elements like bullet points or section breaks, making it dense. The first sentence effectively states the purpose, but subsequent details could be more concise. It earns a 3 for being appropriately detailed yet somewhat verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description adequately covers the tool's behavior: it explains the binding process, failure conditions (empty calibration), carry-forward logic, consistency checks, and build hints. It also describes the relationship with audit_taste. While it could mention more about error cases or parameter validation, the description is largely complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter's meaning. The description adds value by explaining cross-parameter interactions, such as how references are consistency-checked against design_notes, how omitted parameters carry forward, and how the surface string is used for scope matching. This behavioral context enhances understanding beyond mere schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Persist a project's surface calibration for a taste profile — the answers from get_taste_interview.' It specifies the verb 'bind' and resource 'taste surface', distinguishing it from sibling tools like audit_taste (applies bindings) and get_taste_interview (produces interview data). The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: run get_taste_interview first, ask the user, then bind answers. It includes constraints like refusing bindings with no calibration content and the uncalibrated_ack escape hatch for deliberate empty submissions. However, it does not explicitly compare with alternative tools like record_taste_decision, so some guidance on when to use this vs. others is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only (readOnlyHint=true) and non-destructive. The description adds that it 'scans the local Decision Graph' and enumerates the types of issues detected. It also clarifies the behavior of actionable:false as a no-op, which is not in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines purpose, second gives usage advice. Every phrase adds value; no redundancy or extra detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives enough context for an agent to understand the tool's role and behavior. However, without an output schema, it does not describe return format or detailed output for the non-digest mode, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description's parameter details are supplementary. It adds context by describing digest_only as 'hands-off mode' and clarifying that reference_systems can be omitted for a small built-in set. This provides meaningful guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it scans the local Decision Graph for four specific categories (uncovered components, weak rationales, contested decisions, derived staleness). This clearly distinguishes it from sibling tools like audit or decision_get, as it focuses on gap analysis of decision graph health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete usage recommendation: schedulers should call with digest_only:true and treat actionable:false as a no-op. This gives practical guidance, though it does not explicitly contrast with alternatives like audit tools or manual inspection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and non-destructive hints. The description adds valuable behavioral context: it generates an HTML page, supports two layout modes, and can render side-by-side states. This goes beyond annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 sentences), front-loaded with the core purpose, and structured to present modes in a clear hierarchy. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (100% coverage) and annotations, the description is nearly complete. It explains modes and optional states but could mention that the output is a self-contained HTML page (already stated) and that no persistent changes are made (implied by readOnlyHint). Minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds extra meaning by explaining how 'actors' switch layout and how 'ideal' enables side-by-side rendering, providing semantic context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it renders a service blueprint as a self-contained HTML page, distinguishes two modes (single-actor vs two-actor), and uses specific verbs and resource. This differentiates it from all sibling tools, none of which generate blueprints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each mode (single-actor vs two-actor via 'actors' parameter) and the optional ideal-state, providing clear contextual guidance. It lacks explicit when-not-to-use statements, but the context is sufficient given no similar sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it is 'pure offline math', non-destructive, and guarantees minimal changes. It also explains the output includes both foreground and alternative background adjustments with achieved ratio. Annotations already mark readOnlyHint=true, confirming safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loading the main action in the first sentence, and further details in subsequent sentences. No unnecessary words. It is well-structured and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description explains the return format (minimal change, achieved ratio, direction) adequately. It could be more explicit about the exact structure (e.g., whether it returns an array of objects), but the context from sibling audit_contrast likely provides enough guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds minimal extra meaning—it explains that level defaults to AA and that pairs come from audit_contrast output. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: given failing WCAG color pairs, it returns the minimal color change to achieve a target contrast ratio. It distinguishes from brute-forcing by hand and explicitly mentions it feeds from audit_contrast, making its role specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use the tool: after running audit_contrast on failing pairs, to get concrete passing values. It contrasts with manual brute-forcing. However, it does not explicitly exclude cases where pairs are not failing or when other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by explaining the algorithm (per-pixel luminance variance in the bottom strip) and what constitutes clean vs. sliced output, providing concrete behavioral context beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: first sentence states purpose, second explains limitation, third describes method, fourth specifies input. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single parameter and no output schema, the description provides complete context: what it detects, how it works, what inputs are accepted, and the limitation of other methods. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description for 'image_paths' is adequate. The description adds contextual meaning about the type of files (PNG) and the nature of the check, which helps the agent understand the parameter's role beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Detect' and resource 'PNG exports whose content is sliced/cut off at the bottom edge'. This distinguishes it from other audit siblings that check different aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the specific use case (detecting cut-off content) and notes that dimension/ratio checks are insufficient, providing clear context. However, it does not explicitly state when not to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond annotations. It details what checks are performed (44x44pt touch targets, contrast with iOS standard colors, visual rhythm), clarifies that screenshot is for reference and geometry comes from snapshot, and describes the relationship with audit_page. Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and is mostly concise. It includes detailed parameter explanations that are valuable, but could be slightly more compact without losing information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, nested objects, no output schema), the description is complete. It covers all parameters, explains expected input shapes, describes audit checks, and clarifies the return shape via cross-reference to audit_page. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant meaning: it explains the expected shape of elements (label, rect, role, fontPt, etc.), defines viewport, and explains the optional profile and project parameters for binding. It also describes the return shape via cross-reference to audit_page. This far exceeds the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it audits a rendered iOS screen from a view-hierarchy/accessibility snapshot, and identifies itself as an alias of audit_screen with platform:"ios". This provides a specific verb (audit) and resource (iOS screen), and distinguishes it from siblings like audit_page and audit_screen.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives examples of how to call the tool (with no arguments or with elements/viewport), and mentions the return shape is same as audit_page. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., audit_page, audit_screen, other audit tools). No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=true and destructiveHint=false, consistent with the description. The description adds behavioral details: headless chromium rendering, real getBoundingClientRect measurements, and output sorted worst-first. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured, front-loading the purpose and then detailing collected elements, output, and modes. It could be slightly more concise, but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully describes the output format (per-element fix table with selector, role, text, measured sizes, deficit, CSS fix). It covers both modes and default minSize, making it complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning: explains url mode browser requirement, minSize default, and details elements array structure (selector, w, h, etc.). This goes beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool audits tap targets for WCAG 2.5.5 / Apple 44pt, lists the collected elements (a, button, etc.), and explains the output format. It distinguishes itself from sibling audit tools by its specific focus on tap target size.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains two modes (URL vs elements snapshot) and when to use each, including the requirement for headless chromium for URL mode. It does not explicitly state when not to use this tool or mention alternatives, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false; description adds no further behavioral traits but does not contradict. It provides useful context about the breadth of content covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single focused paragraph, front-loaded with purpose, each sentence carries necessary information. No redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two optional parameters and no output schema, the description covers purpose, scope, and usage context thoroughly. Sibling list confirms uniqueness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for both parameters (topic, format). Description adds value by noting 'Omit to return all brand principles' and 'Default: full'. This enriches understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description specifies the tool retrieves brand and visual-design principles, listing concrete subtopics (logo usage, gradients, imagery, hierarchy, system thinking). It clearly distinguishes from sibling tools like get_brand_system or audit tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly states when to use the tool: when user asks about branding, logos, gradients, imagery, etc. It lacks explicit guidance on when NOT to use or alternatives, but context hints at proper scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive. Description adds context about timestamps and calibration use, but does not disclose additional behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey purpose, content, and usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only tool with no output schema, the description adequately covers what the tool returns (trends with timestamps) and how to use the data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters with 100% schema coverage. Description adds no parameter info, but none is needed as the tool takes no input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Get' and the resource 'current brand and visual-design trends', listing specific examples. It distinguishes from sibling tools like get_brand_system by focusing on trends rather than system definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the data as a 'calibration signal, not a prescription', providing guidance on interpretation. However, it does not explicitly state when to use this tool versus alternatives like get_brand_principles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses return content (patterns, guidance, evidence, checklist) beyond the annotations (readOnlyHint, destructiveHint). It adds behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines functionality, second gives usage. Front-loaded with key information. No superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and clear annotations, the description covers purpose, usage, and return format completely. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, baseline is 3. The description adds value by listing the pattern types and contextualizing them (e.g., "moments of truth / recovery"), helping the agent understand the enum semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb "Get", the resource "service design pattern", and enumerates specific patterns (e.g., service blueprinting, human handoff). It distinguishes the tool from siblings by specifying "service design pattern" among many design-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: "when the user is designing a service flow, escalation, cross-channel experience, or moment of truth." It does not explicitly mention when not to use or name alternatives, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying the exact data returned (rule catalog, precedent corpus, bindings) and clarifying that it is not a calibration step. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states what the tool does, second clarifies limitations and recommends alternative. Concise and front-loaded with no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with one parameter and no output schema, the description covers purpose, usage guidelines, return content, and limitations. Complete enough for correct agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'name' with schema description 'Profile name.' Schema coverage is 100%, so the description does not add new semantics beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool loads a locally stored taste profile by name and returns its full rule catalog, precedent corpus, and per-project surface bindings. It distinguishes itself from siblings like get_taste_interview by noting it is not a calibration step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (to retrieve a taste profile's data) and when not to (for design work without a binding, recommending get_taste_interview instead). Also clarifies that bindings are per-surface and do not transfer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: 'Append-only: existing records are never rewritten' and 'accept-verdict precedents suppress matching findings in future audit_taste runs.' Annotations include destructiveHint=true, which aligns with append-only (adds data, doesn't overwrite). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that pack purpose, usage, and key behaviors without any fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and no output schema, the description covers purpose, usage, behavioral notes, and parameter hints. It's comprehensive enough for an agent to use correctly, though a brief example could further aid understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds useful context beyond schema: for 'wrong', it advises 'use a verbatim snippet so accept-suppression can match it.' For 'verdict', it explains the difference between accept and revise/reject. This enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Append a labeled precedent to a taste profile's corpus'. It distinguishes from siblings by specifying the context of audit_taste findings or labeling new wrong→right examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage context is provided: 'Use when a human accepts/revises/rejects an audit_taste finding or labels a new wrong→right example.' It also notes it's append-only, but doesn't explicitly mention when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by noting that 'Template permissions and allowedTokens are cooperative advisory metadata: display labels only, not enforced', which explains behavioral traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with main action. The first sentence states purpose, the second adds important nuance about metadata. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with no parameters and no output schema, the description provides complete context: what it lists, the scope, and a behavioral caveat about metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters; schema coverage is 100% (empty object). Per guidelines, baseline is 4 for 0 parameters. No additional parameter description needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description specifies 'List templates and their registered page pathnames from the active grab session', providing a clear verb-resource pairing. This distinguishes it from sibling tools like list_design_systems or list_content_systems, which operate on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'from the active grab session', giving clear context for when to use. While it does not explicitly exclude alternatives, the context is sufficient to guide selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively details behaviors: rendering, scroll-settling, interaction firing, pixel/DOM capture, and rule engine execution. It also notes the requirement for headless Chromium. Annotations (readOnlyHint, openWorldHint, destructiveHint) are consistent and not contradicted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but somewhat verbose. It front-loads the core purpose and then lists features, with every sentence adding value. However, it could be slightly more concise for quicker parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, no output schema), the description provides a thorough overview of functionality, including the nature of findings (confirmed/likely-artifact/inconclusive). It does not explicitly describe the output structure but gives enough context for an agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 9 parameters have descriptions in the schema (100% coverage), and the description adds significant context beyond the schema. For example, it explains the purpose of 'compact' (drop base64 screenshots to save budget) and 'interactions' (diff against baseline for white-wash detection).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a 'Layer 0 render-and-capture audit' on a live URL, including scroll-settling, interactions, pixel capture, and various visual checks. It distinguishes itself from siblings by emphasizing it catches 'real-world visual nits invisible to HTML-string/geometry audits,' making its purpose specific and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (for visual nits not caught by HTML-string audits) but does not explicitly state when not to use or name alternatives. However, it provides enough context for an agent to infer appropriate usage scenarios, given sibling tools like audit_page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is known. The description adds valuable context: inference of canonical values from corpus, pure offline execution, and detailed output structure. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose, then provides usage instructions, behavioral notes, and output details. Every sentence adds value, and no redundant information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully describes the return values (per-page extraction, consistency dimensions, outlier pages, issues, score, summary). It covers all aspects needed for an agent to understand and use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meeting baseline. The description adds meaning beyond schema by explaining the purpose of each parameter in context, e.g., 'When supplied, hero divergence is measured against this token rather than the corpus modal.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool audits multiple pages for cross-page consistency of container width and hero heading tier, using specific verbs and resources. It distinguishes itself from siblings like audit_page by focusing on cross-page consistency rather than single-page evaluation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to pass ≥2 pages from different routes on the same site, and flags the blind spot where pages pass audit_page but disagree. This provides clear when-to-use and when-not-to-use guidance, and references the alternative audit_page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, which align with the description's detection purpose. The description adds rich behavioral context: how to invoke each check, what it flags (object-fit:cover crop, Ken Burns pan/zoom, truncated edges), and even a DevTools snippet note. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into three checks and front-loads the purpose. However, it is somewhat verbose (e.g., repeating examples) and could be slightly trimmed without losing clarity. Still, it effectively communicates the tool's functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the three parameters and no output schema, the description completely explains what each check does, how to invoke it, what inputs to provide, and what failures it catches. Examples enhance understanding. No missing information for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds significant value beyond the schema by grouping parameters into the three checks and explaining their purpose (geometry, motion, edge). It also clarifies the format for clips (first/last frame PNG paths) and how to use the geometry check with or without args.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detects cropped content in device-mockup frames, listing three specific checks (GEOMETRY, MOTION, EDGE). The verb 'detect' and resource 'device-mockup frames' are specific, and it distinguishes itself from sibling auditing tools by focusing on frame cropping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use the tool (to detect cropped content in device frames) and provides concrete examples (16:9 clip in 1.82-AR screen). However, it does not explicitly state when NOT to use it or mention alternatives among siblings, though 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; description adds transparency about the two-step workflow and what each call returns. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, zero unnecessary words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what the tool does, how to use it (two-step), what it returns (snippet then scores), and its relation to sibling tools. No need for output schema given clear verbal description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds meaningful context: explains that first call returns snippet, second call uses elements and viewport. Goes beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it evaluates visual rhythm from rendered page geometry, describes two-step process, and differentiates from sibling audit_page by focusing on things only visible once rendered.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use this tool (for rendered visual rhythm) and how it complements audit_page. Provides step-by-step usage: call with no args first, then with JSON.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, and the description confirms it renders and writes HTML files (destructive). It adds context that portraits are generated from the local store and that profile rules bind in full. No annotation contradictions. Could potentially mention that output files are written to output_dir, but the schema covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary purpose, followed by parameter behavior and verification guidance. Every sentence adds essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and annotations, the description covers purpose, parameter semantics, and important usage context (verification, acceptance criteria). It is fully sufficient for an agent to understand when and how to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant meaning beyond schemas: it explains that omitting 'project' renders every binding plus a gallery index.html, and that 'output_dir' is where files are written. This clarifies parameter usage and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders a Taste Engine surface as an HTML portrait, and distinguishes between rendering one binding (with project) versus all bindings plus gallery (omit project). It also specifies that it uses the local taste store, differentiating it from sibling tools like audit_taste or decision tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use the tool: pass 'project' for a single binding, omit for all bindings plus gallery. It also provides post-usage guidance: verify with audit_taste using document_kind:'portrait' and clarifies that design_notes are not acceptance criteria. This helps the agent choose correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false. Description adds context about output content (id, category, severity, taste scope, principle source) and clarifies no scanning occurs. No contradictions; the behavioral disclosure is clear and consistent with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first covers purpose and output, second gives usage guidance. Every word adds value; no filler. Well-structured and front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only enumeration tool, the description provides all necessary information: what it does, what fields are returned, when to use it, and how it differs from a sibling. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so baseline is 4. Description does not need to add parameter meaning; it correctly omits any parameter discussion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool enumerates the detector rule corpus, listing specific fields (id, category, severity, taste scope, citation source). It explicitly distinguishes from sibling talon_scan by contrasting 'No scan required' and recommending use before or instead of scanning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'use this to show a client why before or instead of running talon_scan.' This tells when to use (for explanation) and when not (if scanning is needed), with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds significant behavioral context: it's deterministic, returns questions with skippable/priority, voice question format, refine mode behavior (requires existing binding, per-dimension adjustments), and structure of compressed vs full interview. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely verbose with multiple paragraphs containing extensive detail. While every sentence adds value, it lacks conciseness and could be better organized for quick scanning. Front-loads the main purpose but then goes into exhaustive specifics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description thoroughly explains the return structure: questions with properties, more_questions for optional depth, refine mode behavior, and special question with suggestions. It covers all aspects of the tool's behavior and usage for both modes and depths, making it complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description enriches parameter meaning: explains mode defaults to 'kickoff', depth defaults to 'first_run', and details the effects of each enum value (e.g., refine requires existing binding, full flattens questions). It also clarifies that profile is required and project is optional, adding context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a deterministic calibration interview for taste profiles, specifying it as the starting point for new projects. It distinguishes between depth modes and explains the resource (taste interview) and action (get), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'START HERE on a NEW project', 'Run this BEFORE the first audit_taste on any project that has no binding yet', and when to use mode:'refine' instead of starting over. It also tells what to do with the output (ask questions, persist via bind_taste_surface) and mentions audit includes calibration_hint when missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that scores are deterministic and that launching headless chromium happens only when url is provided, which goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough but slightly verbose. However, every sentence adds value, and it is well-structured with clear sections for input, output, and comparisons.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (multiple inputs, outputs, relation to audit_page, and guidance for non-mechanical categories), the description covers all necessary context comprehensively. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters have schema descriptions, and the description adds meaningful context: url triggers rendering, strict counts warnings as failures, containerMaxWidth is for responsive checks. This enhances the schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool scores an HTML/CSS page across 7 design categories with 0–10 ratings, plus an overall score and grade. It distinguishes from audit_page by noting deterministic checks without a browser unless a URL is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to pass html directly vs url (triggers headless chromium for rendered DOM). Mentions that brand, conversion, and motion categories are not mechanically assessed and directs users to other tools, providing clear alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![raven-mcp MCP server](https://glama.ai/mcp/servers/rhinocap/raven-mcp/badges/card.svg)](https://glama.ai/mcp/servers/rhinocap/raven-mcp)

Score Badge

Copy to your README.md:

[![raven-mcp MCP server](https://glama.ai/mcp/servers/rhinocap/raven-mcp/badges/score.svg)](https://glama.ai/mcp/servers/rhinocap/raven-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rhinocap/raven-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server