Raven MCP

by rhinocap

Overview Schema Source Related Servers Score Discussions Admin

JavaScript

Hybrid

Server Quality Checklist

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

Latest release: v2.5.1
Disambiguation3/5
The long, heavily detailed descriptions help separate most tools, but there is real overlap at the set level: `audit` is an explicitly recommended catch-all for the two dozen individual `audit_*` tools, and `audit_screen`/`audit_ios_screen` are effectively the same check. With 111 tools, an agent must rely on lengthy prose rather than clear boundaries to avoid mis-selection.
Naming Consistency3/5
The dominant convention is snake_case `verb_noun` (`get_`, `list_`, `create_`, `audit_`), so the set is readable overall. But it mixes in noun-first and domain-first forms such as `decision_*`, `gap_scan`, `talon_scan`, and `raven_reflect`, plus abbreviations like `audit_rn` and `audit_ios_a11y`, so the naming is not fully predictable.
Tool Count1/5
111 selectable tools is far beyond any reasonable single MCP surface and well past the 50+ threshold. Many related operations, especially the roughly two dozen `audit_*` variants, could be grouped into a single parameterized tool or split into separate sub-servers. The breadth may be intentional, but this namespace is a heavy burden for agent selection.
Completeness4/5
The domain coverage is unusually comprehensive: reference capture, design-system token management, knowledge lookup, taste calibration, creative generation, decision graphs, and a wide range of audits all have lifecycle support. The main gaps are minor operational lifecycle operations, such as no apparent delete/cancel for creative generation jobs or brand profiles, and no universal update/delete path for every stored artifact.
Average 4.1/5 across 111 of 111 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- 9 of 10 community issues answered or closed in the last 6 months
- 849 commits in the last 12 weeks
- Last stable release on August 22, 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

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description characterizes the tool as a safe read operation ('Read ... without deleting their durable change records'), while annotations mark it as destructiveHint=true and readOnlyHint=false. This is a direct behavioral contradiction: either the description understates destructive side effects or the annotation mislabels the tool. The agent cannot rely on either 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 tool is concise and front-loads the core action in the first sentence, but the second sentence ('A batchCommit marker is the signal... to implement the unified pending batch') introduces opaque, implementation-heavy language that is not actionable for an agent. It is not fatally verbose, but it does not earn its place.
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 no output schema and no description of what is actually returned after reading the grab selections, and the behavior is made less safe by the annotation contradiction. The cryptic batchCommit sentence hints at a workflow contract but does not explain how the agent should recognize or respond to that condition, leaving the description insufficient for correct 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?
There is only one optional parameter, and the schema description already covers its meaning: 'Optional wait timeout in milliseconds'. The description merely restates 'optionally waiting up to timeout_ms', adding no new semantic detail beyond the schema, so the high-coverage baseline of 3 applies.
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 opens with a clear verb and resource: 'Read newly sent grab selections' and adds a meaningful qualifier ('without deleting their durable change records'), which helps distinguish a reading tool from a purging one. It could be strengthened by explicitly naming how it differs from sibling tools like get_grab_layers or get_grab_operation, and the second sentence's batchCommit jargon muddies 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'newly sent grab selections' and 'batchCommit marker' give implied context for when this should be used, but no explicit alternatives or exclusions are provided. An agent would still need to infer the tool's role among 100+ siblings, and there is no guidance about what to use if destructive behavior is desired.
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?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool produces principles, violations, and improvement suggestions, but it does not add behavioral detail such as output size, the meaning of compact mode, or the before/after diff behavior. No contradiction with annotations 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?
The description is a single tight sentence with no filler, front-loading the core action and then listing the three output categories. It earns its place and avoids duplicating schema details.
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 six optional parameters and no output schema, the description leaves important context implicit: it does not explain whether a text description, screenshots, or both are needed, nor does it describe the structured pixel diff returned when both before and after screenshots are supplied. The compact mode payload rationale is only present in the schema, not reflected in the description, so an agent has to infer key invocation 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 description coverage is 100%, so the schema already documents each parameter clearly. The main description adds no new parameter-level semantics beyond the general 'evaluate design' idea. This fits the baseline score of 3 for a tool whose schema has fully documented 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 uses the specific verb 'Evaluate', names the resource ('design description'), and binds the operation to 'UX principles'. It also states the return contents: relevant principles, potential violations, and improvement suggestions. It does not explicitly distinguish itself from the many audit_* siblings, but the wording is specific enough that an agent can infer its intent.
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?
There is no guidance about when to choose evaluate_design over the many related audit_* or get_* tools. No conditions, exclusions, or alternative tool names are mentioned, so an agent must infer the appropriate context from the tool's name and generic description.
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 cover the read-only, idempotent, non-destructive safety profile, so the bar for behavior disclosure is lower. The description adds useful output-shape context by stating the returned components (do's, don'ts, evidence, checklists), which matters because there is no output schema. It does not disclose more behavioral detail such as behavior on invalid or unsupported type values.
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 single focused sentence with the main verb-object relationship front-loaded. The long list of pattern types is somewhat heavy, but each listed item is informative and supports correct parameter selection. No filler or redundant restatement of the tool name, though the sentence is a bit list-heavy.
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 absence of an output schema, the description usefully states what the return content includes and lists supported pattern domains. The annotations handle safety/idempotence, and the schema handles parameter semantics. A minor gap is lack of explicit discrimination from the several similar get_* sibling tools, especially get_principles and get_checklist.
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 three parameters. The description's enumerated pattern categories overlap with the type parameter's examples but do not add exact syntax, normalization rules, or behavior of the goal/platform filters beyond the schema. This meets the baseline but adds little extra semantic value.
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 identifies the action ('get'), the resource ('UI/UX patterns'), and what is returned ('do's, don'ts, evidence, and checklists'). It names specific pattern types, making the tool's scope fairly concrete. It does not explicitly differentiate itself from siblings like get_principles, get_checklist, or get_content_pattern, but the combination of 'patterns' and the enumerated design types makes the core 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says what the tool returns but gives no guidance on when to prefer it over similar siblings such as get_principles, get_checklist, or get_content_pattern. There is no stated when-to-use/when-not-to-use context, no exclusions, and no alternatives named.
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, idempotentHint, and destructiveHint, so the safety profile is well covered. The description's verb 'Browse' aligns with those annotations and does not contradict anything. Although no deeper behavior like sorting or response limits is disclosed, the annotations reduce the need for additional 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and object before enumerating categories. The category list is long but relevant to the browse use case, and there is no redundant 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 read-only listing tool with full schema coverage, the description supplies the domain and purpose without demanding an output-schema explanation. It is not exhaustive (e.g., no pagination or response structure), but those omissions are minor given the low complexity and available annotations.
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 both parameters (search and media_type), so the baseline is 3. The description does not discuss either parameter directly; its category list does not map to the media_type enum. It neither harms nor extends parameter understanding beyond the schema.
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 explicitly states a verb ('Browse') and a resource ('Raven creative presets'), and it enriches the purpose by listing the categories of presets (product photoshoots, marketplace cards, UGC ads, etc.). It distinguishes itself from adjacent list_* tools through the preset domain, though it does not explicitly call out a sibling alternative, so a 4 rather than 5.
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 when, when-not, or alternative tool guidance is provided. The description does not tell the agent when to use list_creative_presets versus list_creative_models, list_templates, or other listing tools. The use case is only implied by the noun 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?
The description adds useful behavioral nuance: the write is batched into a single DESIGN.md update, and roles/flexible metadata are advisory, not enforced. The annotations already communicate read/write semantics, idempotency, and destructiveness, and nothing in the description contradicts them.
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 short and front-loaded: the main action appears in the first sentence. The second sentence adds important advisory semantics, but it is dense and references an input not present in the schema, slightly reducing the precision of the extra detail.
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 mutation tool with destructiveHint: true, the description explains the batching and the advisory nature of slots, and the schema covers all parameters. However, it does not mention what happens to existing slots for the page, whether this overwrites or merges, or what the response of a successful or failed call looks like.
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 already has 100% coverage of page, slots, and template_id, so a baseline of 3 applies. However, the description references 'allowedTokens' as if it were meaningful input data, yet the slot object permits only slotId, selector, and role with additionalProperties: false. This makes the description actively misleading for parameter construction despite the schema's completeness.
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 states a specific verb ('Persist') and resource ('page-scoped template slots') in a batched DESIGN.md update, so an agent can tell roughly what the tool does. It does not explicitly distinguish this tool from the generic update_design_md sibling, though 'template slots' and 'batched' imply a narrower scope.
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?
There is no explicit guidance about when to use this tool instead of alternatives like update_design_md, get_page_template, or read_design_md. The intended context must be inferred entirely from 'page-scoped template slots' and 'batched ... update.'
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?
The description does add behavioral context: it returns pass/fail per check with fix instructions, and it explains how containerMaxWidth changes the max-width check from a generic 1200px heuristic to a token-aware divergence check. However, annotations state readOnlyHint=false, idempotentHint=false, and destructiveHint=true, while the description's 'audit' language implies a non-mutating analysis and never discusses side effects that would justify the destructive mismatch. This is a nontrivial gap, but not a direct 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 dense but appropriately so for a tool with 9 parameters and five audit categories. Every clause earns its place, and the purpose and the main parameter special-case are front-loaded. It is a single long sentence rather than a scannable structure with bullets or paragraph breaks, so slightly less structured than ideal.
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 gives a decent overview of what the audit covers and roughly what it returns, but there is no output schema and the return-value description is incomplete—it does not mention score, grade, screenshots, passes list, or fix_priority, though some of this is inferable from the compact parameter description. It also does not state whether at least one of url or html is needed and does not address the many sibling audit tools that might be the better choice.
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 (89%) and the schema already describes each parameter, so the baseline is 3. The description nonetheless adds semantic value for containerMaxWidth by explaining how it affects the heuristic, what 'token-aware' means, and the fact that it flags containers that are either too narrow or too wide. This goes beyond the schema's basic description.
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 opens with a clear verb and resource: 'Audit HTML/CSS against Raven's design quality standards,' then enumerates several concrete check domains, so an agent can easily recognize this is a broad page-level design audit rather than a single-issue audit. However, it never explicitly contrasts itself with the many specialized audit_* siblings (e.g., audit_typography, audit_contrast, audit_url), so it is clear but not fully differentiated.
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 say when to prefer this tool over an audit_* sibling or when not to use it. There is no alternative route or exclusionary context. The only conditional usage advice is about the optional containerMaxWidth parameter, which is parameter guidance, not tool-selection 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 establish that the action is mutating and destructive, and the description's 'add' aligns with that. It adds useful context that the decision is 'active' and stored in the 'local' Decision Graph, but it does not disclose side effects such as whether an existing active decision is overwritten or superseded.
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, front-loaded sentence with no filler or repetition. Every word contributes to defining what the tool does.
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 mutating tool with six parameters and no output schema, the description is accurate but minimal. It does not explain what being an 'active decision' means or how this call relates to the decision lifecycle, so an agent can invoke it but not fully anticipate its consequences.
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 already provides 100% parameter coverage, describing each field including scope, statement, component_ref, rationale, author, and alternatives_rejected. The description adds no disambiguation beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Add') and a specific resource ('an active decision to the local Decision Graph'). It communicates that the tool creates a decision record, but it does not explicitly contrast itself with sibling tools like decision_commit, decision_draft, or decision_import, so its scope is slightly dependent on inference.
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 gives no guidance about when to use this tool instead of the many related decision tools. It implies that you call it when you need to add an active decision locally, but it does not mention alternatives, 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?
The description is consistent with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. It adds the useful context that the tool operates on a local file, but no further behavioral traits like missing-file handling or output expectations are disclosed.
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 concise sentence with no filler. The key verb, resource, and source are front-loaded, making it easy to scan.
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 schema and annotations provide enough to invoke the tool, but the absence of an output schema and any mention of the return payload leaves a gap. The description also does not clarify how this relates to the very similar 'read_design_md' and 'list_design_system_components' 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 coverage is 100% and both parameters already have meaningful descriptions. The tool description does not need to add parameter-level detail; the baseline 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 states a clear action ('Read'), a specific target ('component declarations and tokens'), and a precise source ('local DESIGN.md file'). It is easy to understand, but it does not explicitly distinguish itself from closely related sibling tools like read_design_md or list_design_system_components.
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?
There is no guidance about when to use this tool versus the many design-system read/list siblings. The agent must infer usage from the name and description alone.
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 destructive and idempotent behavior. The description adds useful context by saying the Markdown body is preserved and the edit is surgical, which mitigates the destructive hint somewhat. Still, it does not clarify that remove/rename operations can delete or move tokens, nor mention any irreversible effects in more detail.
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 short, front-loaded sentence with no filler. Every phrase contributes meaning: the resource is named, the operation is scoped to one token, and the important preservation guarantee is clearly stated.
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 tool with nested operations (set, remove, rename), no output schema, and a destructive annotation, the description is adequate but not fully complete. It signals the core constraint and preservation goal, and the schema provides parameter details, but the description itself does not prepare the agent for the alternate mutation modes or the outcome of applying them.
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 description coverage is only 25%, and the description does little to compensate. It conveys granularity (one token) but does not explain the set, remove, and rename operation objects, their aliases, or how to choose between them. The added parameter-level meaning is therefore minimal.
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 identifies the verb ('Update') and the specific resource ('one DESIGN.md token'), and the phrase 'while preserving the Markdown body' adds meaningful scope. However, it does not explicitly distinguish itself from sibling tools like read_design_md or init_design_md, so it stops short of full sibling differentiation.
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 phrase 'one DESIGN.md token surgically' implies use for targeted token edits and preservation of the Markdown body, giving some contextual guidance. But the description never states when to prefer this tool over alternatives, when it should not be used, or which sibling to choose for broader design-file rewrites or reads.
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?
The description states that this saves a source-file configuration, which adds some context about persistence. However, it does not mention that this overwrites an existing configured source or how the change affects future inventory/diff operations; the destructiveHint annotation is carrying most of the risk disclosure.
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 single sentence is short, front-loaded with the action verb, and clearly communicates the central purpose. It loses little from being more structured, example, or explaining the .raven config location.
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?
With 5 parameters, a nested object, and no output schema, the description is rather minimal. The schema fills most knowledge gaps, but the description would benefit from noting the persistent/overwriting nature of the action, any required environment ordering (for example ensuring DESIGN.md exists), or how aliases relate to the source file.
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 project_dir, source_kind, platform, aliases, and design_file_path. The description only adds the fact that the design file is local and used for inventory/comparison, which contributes little beyond the schema.
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 ('Save') and the target resource (the local DESIGN.md file Raven should use), and it connects to the tool's inventory/comparison purpose. It differentiates the tool from generic read/update operations but does not explicitly distinguish it from sibling configuration-like tools such as 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 intent of using this during setup for design-system inventory/comparison is implied, but there is no explicit 'use this when' guidance, no exclusion for editing/reading DESIGN.md, and no comparison to alternatives like update_design_md or read_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?
The annotations already convey read-only, idempotent, non-destructive, and open-world behavior, so the description doesn't need to repeat them. It adds no extra behavioral context such as whether the output is static knowledge, generated content, or a generalized strategy, which leaves some ambiguity for a no-output-schema 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?
The description is compact and front-loaded with the main verb and resource, followed by a concise list of covered strategy areas. Every sentence earns its place without unnecessary 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 two-parameter read-only lookup tool, the description plus schema is mostly sufficient: the primary type and optional stage are clear, and annotations cover safety. It still lacks explicit sibling differentiation and output-shape expectations, but the overall context is enough for an agent to make a reasonable call.
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 the description largely restates the type options already present in the schema. The stage parameter and its contextual filtering are already described in the schema, so the description adds little parameterization value beyond reinforcing the topic list.
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 uses 'get' as the verb and defines the resource as business and monetization strategies for digital products, with a concrete list of covered topics. It is distinct from the majority of audit/design sibling tools, though it does not explicitly differentiate itself from semantically related siblings 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?
There is no explicit guidance on when to choose this tool over alternatives, and no mention of when not to use it. The description implies context through the listed topics, but the agent is left to infer when this tool is the right one among many similar knowledge-retrieval 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needs to add behavior beyond that. It adds the default return shape (token categories and DTCG/CSS/flat formats), which is useful in the absence of an output schema, but it says nothing about behavior for unknown IDs, missing token groups, or the size of an unfiltered response.
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 front-loaded sentence with zero filler: the purpose is stated first, then all supporting detail is compressed into one clause. The token-category enumeration is slightly redundant with the group parameter schema, so it is not perfectly minimal, but every remaining word carries usable 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?
For a simple read tool this is broadly sufficient: the schema documents all three parameters fully and annotations cover side-effects, while the description signals the default response shape (token groups and formats) despite there being no output schema. Notable gaps are the lack of guidance on discovering a design system ID, confirmation that all groups are returned by default, and any edge-case behavior for invalid IDs.
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 baseline is 3: every parameter, including the format enum with defaults, is already documented in the schema. The description mostly restates those same values with slightly richer labeling ('W3C DTCG, CSS custom properties, or flat'), adding meaning but not compensating for any coverage gap.
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 opens with a specific verb-resource pairing: 'Get design tokens for a specific design system', and enumerates the token categories and output formats. 'Specific' plus 'design tokens' clearly distinguishes it from list_design_systems, get_brand_system, and list_design_system_components, though it does not name any sibling explicitly.
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?
Usage is only implied: the token categories and formats suggest this is for retrieving design token values for a chosen system. However, there are no explicit conditions, exclusions, or alternatives given — for instance, no pointer to list_design_systems for discovering valid IDs or to get_brand_system for non-token brand data — leaving routing decisions entirely to the agent.
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 the tool read-only, idempotent, and non-destructive, so much of the behavioral burden is covered. The description adds that this is specifically about brand voice systems, which adds context, but it does not disclose return shape, pagination, or any limitations. With read-only annotations in place, the added behavior context is moderate rather than 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?
A single, front-loaded sentence states what the tool offers and immediately grounds it with examples. Every word earns its place on, and no unnecessary context is included.
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-only list with two optional params and a schema documenting both, the description communicates the core purpose and scope effectively. It does not mention return fields or how this differs from sibling listing tools, but those are not essentials for an agent to understand what the tool invokes.
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 already describes both parameters, with the search parameter covering name, description, or tag and the category parameter listing all allowed categories. The description merely paraphrases 'filter by category or search by name' and actually under-specifies search scope, so it adds almost no value beyond what the 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?
The description clearly states the verb ('Browse') and resource ('content design systems'), and explains they are brand voice and tone guides with concrete examples. It does not explicitly contrast itself with siblings like list_design_systems, but the examples make the focus reasonably distinct.
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 explains how to filter, not when to use this tool versus alternatives. It gives no cues for choosing list_content_systems over sibling list_design_systems or get_content_system, so an agent must infer the appropriate context from the tool name and examples.
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 readOnly, idempotent, openWorld, and non-destructive hints. The description adds behavioral transparency about live adversarial queries and the specific verdict categories returned, which are not inferable from annotations alone. There is 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?
The description is two tight sentences with front-loaded action and no filler. Every sentence earns its place: the first explains the operation and output, the second clarifies the key value proposition.
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 captures the high-level purpose and output verdicts, but the tool has complex nested parameters and no output schema. It does not fully describe how query expectations should be expressed or how the expected_shape_schema should be structured, though much can be inferred from the schema itself.
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 description coverage is 0%, and the description does little to explain the three required parameters beyond mentioning an expected shape schema and per-query expectations. Property names like endpoint_url, queries, and expected_shape_schema are somewhat self-explanatory, but the description fails to enrich their meaning or explain nested expectation fields.
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 states a specific verb and resource: it runs adversarial queries against a live endpoint and returns per-query verdicts. It clearly conveys the tool's unique purpose of catching shape-valid but wrong responses, but it does not explicitly distinguish itself from sibling tools like audit_contract.
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 a live API's responses need adversarial validation against both a shape schema and per-query expectations. It does not provide explicit exclusion criteria or alternatives, so the guidance is implied rather than 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 mark readOnlyHint false, destructiveHint true, and idempotentHint true, so the description does not need to repeat those. It adds a 'commit/confirm' semantic but does not disclose what happens to the existing draft, whether rationale is overwritten, or what a successful call returns.
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 purposeful sentence with no filler. Every phrase contributes: the action, the object, and the target decision state are all included.
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 parameter schema and annotations, the definition is enough for basic invocation, but not complete for a mutation tool. There is no output schema, and the description does not clarify what 'commit' does to the decision lifecycle, so an agent must infer side effects and return 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?
The schema already describes all three parameters fully, so the description is not heavily burdened here. It reinforces 'rationale' as the confirmed rationale, but adds no extra meaning for 'id' or 'similarity_threshold' beyond the schema.
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 names a concrete action ('commit or confirm') and a clear object ('the rationale for a decision'), so the purpose is understandable. It also scopes the target to 'draft or extracted' decisions, but it does not explicitly differentiate itself from the many sibling decision_* tools such as decision_draft or decision_evidence.
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?
'For a draft or extracted decision' gives a useful usage context, but it does not say when this should not be used or mention an alternative among the decision_* family. The intended workflow position is implied rather than spelled out.
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=false and destructiveHint=true, and the description adds the useful behavior that the reason is intentionally left out at draft time. It does not clarify what side effects occur, whether an existing draft is overwritten, or what 'later confirmation' concretely requires.
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 clean sentence with no filler, and the most important behavior, 'Capture a decision,' is front-loaded. The deferred-rationale clause earns its place by clarifying that this is a draft action.
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 core action and the deferred-rationale behavior are present, and the input schema covers all parameters. However, with no output schema and a destructiveHint=true annotation, the definition leaves the concrete result of the operation and the handoff to finalization tools like decision_commit somewhat ambiguous.
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 fully documents all four parameters, so the description does not need to repeat their syntax. The description usefully signals that a 'why' field is absent by design, but it adds no per-parameter information beyond what schema descriptions already provide.
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 names a specific action ('Capture a decision') and a source/context ('working context'), and it clearly signals the provisional nature by saying the rationale is deferred for later confirmation. It does not explicitly distinguish itself from the sibling decision tools like decision_commit or decision_add, so full differentiation is left mostly to the tool name.
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 phrase 'why deferred for later confirmation' implies this is for interim decisions that are not fully reasoned yet, which gives some usage context. However, it never explicitly says when to use this versus decision_commit, decision_add, or decision_supersede, nor does it 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as not read-only and as destructive, so the description does not need to re-establish the mutation profile. The description adds that the target must be an existing decision, but it does not disclose behavior like whether the evidence is appended, replaces prior evidence, or what side effects may occur.
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 compact sentence contains the key action, resource, and scope. It is front-loaded and contains no filler words or redundant qualifications.
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?
With six parameters, no output schema, and a mutation-focused sibling suite, the description gives the minimum viable context. It identifies the action and target, but leaves behavior details such as validation failure modes, return value, and interaction with decision history unstated. Annotations cover some of the safety gap, but this is not complete enough for complex tool-use routing.
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 has full coverage with descriptions for all six parameters. The description adds nothing to parameter meaning beyond the schema, so the baseline score of 3 is appropriate. 'Quantitative or qualitative' adds no extra semantic weight because type enum already captures this.
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 a specific verb ('Attach') and clearly identifies both the object (evidence) and the scope (an existing decision). It distinguishes itself from creating decisions through the word 'existing', though it does not explicitly name or reference sibling alternatives.
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 context is implied: use this when attaching quantitative or qualitative evidence to an existing decision. It does not explicitly describe when not to use it or which sibling tools to use instead, such as decision_add for creating decisions or decision_commit for finalizing them.
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?
The description adds one meaningful behavioral beyond annotations: imported history is review-only until decision_commit. That is valuable. However, annotations mark this tool as destructive and readOnly=false, and the description does not explain what (if anything) gets changed, overwritten, or destroyed, or why it is unsafe. It does not directly contradict the annotation, but it also does not clarify it.
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 in 24 words: the first states the core operation at front, and the second adds the workflow gate. Every sentence has a direct purpose, with no 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 schema covers parameters and there is no output schema to explain. The description gives overall behavior and the review-only boundary, but remains thin on how the resultant prompts are delivered and what the destructiveHint means in practice. A capable agent could make the call, but would be guessing about side effects and outputs.
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 four parameters are already adequately documented. The tool description adds no per-parameter meaning, such as how repo_path, doc_globs, max_commits, or max_chunk_chars affect the extraction, but the schema provides the necessary baseline.
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 first sentence uses a specific verb ('Mine') and resource ('local git history and decision-bearing Markdown'), and states the output is 'provenance-tagged Decision Graph extraction prompts.' It is clear but does not explicitly differentiate itself from the many sibling 'decision_*' tools, so it earns a 4 rather than a 5.
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 phrase 'remains review-only until decision_commit' gives useful workflow context, implying this tool is the staging step before decision_commit. However, it never explicitly states when to use this tool versus sibling alternatives, nor does it give conditions to avoid it, so usage guidance is only implied.
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?
The description aligns with annotations: destructiveHint=true, readOnlyHint=false, and idempotentHint=false, indicating this is a mutating operation. It clarifies that scopes are narrowed and the likely effect is that both decisions stay active, but it does not disclose side effects, whether previous scopes are overwritten, or what happens if the scopes are not actually distinct.
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 with no excess wording, repeating, or structural clutter. It presents the core action and intended result front-loaded and reads clearly.
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 four-parameter mutating tool with no output schema, the description is reasonably complete but leaves some practical gaps: it does not define what a valid 'scope' looks like, whether the two scopes must be non-overlapping, or what the agent should do before/after calling. The full schema and annotations help, but a little more conceptual context would make this tool safer to use.
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 four parameters already have meaningful descriptions: id_a/id_b identify existing decisions and scope_a/scope_b are the narrowed scopes. The tool description adds no extra parameter-level guidance, which is acceptable because the schema already carries the full semantic load.
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 a specific verb ('narrow') with a clear resource ('two decisions' and their 'scopes') and the intended outcome: both decisions can remain active. This distinguishes it from generic get/list/commit tools, though it does not explicitly name sibling tools like decision_supersede or decision_contest.
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 phrase 'so both can remain active alongside one another' implies when this tool should be used: when two decisions would otherwise conflict or overlap and both need to be kept. However, it gives no explicit guidance about when not to use it or when to prefer a sibling tool such as decision_supersede.
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 central claim that the tool queues an intent 'without mutating the live page' directly conflicts with the annotation destructiveHint=true. A caller cannot safely tell whether this call is destructive or purely non-mutating. The description otherwise provides useful behavioral context (preview semantics, rejected roles, scoping exclusions), but the contradiction is severe enough to make the transparency score invalid.
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?
Every sentence in the description carries distinct information: core behavior, operation semantics, preview mode, permission behavior, and scope limitations. The structure is front-loaded with the most important fact and contains no redundant phrases or filler.
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 17-parameter, 8-required-parameter tool with no output schema, the description covers only part of the surface: operation selection, preview/proposed mode, and scope boundaries. It does not explain how orderedSelectors/indices/snapshot hashes fit the invocation, nor what the queued intent returns or how it is later consumed. It is a solid baseline but not complete for a tool with this level of 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?
The description adds real value beyond the raw schema: it explains operation variants, ties reorder to parentSelector and reparent to toParentSelector, clarifies that roles are not caller-suppliable, and explains the meaning of measuredRects. However, with only 24% schema description coverage, important required fields such as fromIndex, toIndex, orderedSelectors, approximate, and domSnapshotHash remain semantically unexplained, so the compensation is only partial.
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 a specific action ('queue a same-page layer reorder or reparent intent') against a clear resource ('layer'), and distinguishes the behavior from direct live-page mutation. It also distinguishes the two operation modes (reorder vs reparent), which makes the tool instantly recognizable among the large 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives operation-specific guidance: reorder uses a single parentSelector, reparent uses toParentSelector, and measuredRects determine preview vs. proposed behavior. It also bounds scope to same-page and excludes shadow-root/iframe boundaries. It does not explicitly name alternative sibling tools or prerequisites such as starting a grab session, so it falls just short of full cutoff 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?
The description adds useful behavioral context beyond the annotations by stating that both decision nodes and their lineage are preserved. This helps an agent understand that the operation is not a simple deletion even though destructiveHint is true. It does not contradict the annotations and gives a meaningful guarantee about what survives the 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 a single concise sentence that leads with the core action and then explains the important preservation guarantee. There is no wasted text, jargon, or repetition of the schema. Every phrase 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 tool's simple two-parameter surface, the absence of an output schema, and the annotations covering mutation/destructive behavior, the description is reasonably complete. It tells the agent what kind of relationship to create while assuring that the original nodes remain intact. It could say more about side effects or return values, but for this tool's complexity it is 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?
The input schema already provides full descriptions for both required parameters, old_id and new_id, with 100% coverage. The description does not add extra parameter-level detail, but none is necessary because the schema carries the semantic weight. It correctly implies that these are the two existing decisions involved in the supersede operation.
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's verb and resource: 'Explicitly supersede one decision with another.' It also adds a meaningful qualifier that both nodes and lineage are preserved. However, it does not explicitly differentiate itself from related sibling tools like decision_commit or decision_scope, so an agent gets semantic clarity but not direct sibling routing.
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?
There is no guidance about when to use this tool versus the other decision_* siblings. The description implies the obvious use case—superseding an old decision with a new one—but never states exclusions, prerequisites, or alternatives. An agent must infer the intended context from the tool name and description alone.
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, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful context about the content categories returned, but does not disclose return shape, whether the full object is returned by default, or what happens when the section parameter is used; these are partially covered by the schema.
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 tool's primary purpose and then efficiently enumerates the content categories. There is no filler or repetition, and every clause adds relevant 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-only resource fetch, the description plus the annotated schema provide enough context to use the tool correctly. It might be slightly stronger with an explicit note that all sections are returned when no section is specified, but the section parameter's 'Default: all' already carries that information.
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 the id and section parameters already well documented, including the section enum and default. The description adds no significant extra parameter semantics beyond already enumerated by the schema.
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 names the resource being fetched: a brand's content design system, and goes beyond that by listing the exact components included (voice, tone shifts, vocabulary, grammar, content patterns, inclusive language). It does not explicitly differentiate from sibling tools like get_design_system, get_content_pattern, or get_content_principles, but the target is clear 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when this tool should be used — when a caller needs content voice, vocabulary, grammar, or content-pattern guidance for a brand. However, it gives no explicit guidance about when not to use it or how it relates to siblings such as get_content_pattern or get_design_system.
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 states that while storage happens, 'Raven makes no model or network call,' which is a useful behavioral disclosure beyond the annotations. It also correctly implies this tool only returns a prompt rather than performing extraction. Annotations already provide read-only, idempotent, and destructive hints, so the description does not need to re-state all of 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?
Two concise sentences deliver the core purpose, the return value, and an important behavioral boundary. No filler or redundant wording appears, and the most actionable 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, has a fully documented schema, and uses annotations to communicate safety characteristics. The description says what the tool stores and what it returns, which is enough for an agent to call it correctly, though an explicit mention of what 'store' implies semantically would strengthen 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?
The input schema already covers 100% of the parameter descriptions, including text and source_meta semantics. The tool description does not add any additional meaning about how the parameters map to the extraction prompt, but it also does not need to because the schema carries that information.
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?
States a specific verb and resource: 'Store a transcript source' and the return result: 'an extraction prompt'. The second sentence clarifies the tool is not actually invoking the model, which makes the intended purpose unambiguous. It does not explicitly contrast itself with sibling tools like ingest_transcript_results, but the purpose is still clear from the description alone.
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 implies the tool should be used when a transcript source needs to be stored so an extraction prompt can be returned to the calling agent's model. However, it provides no explicit when-to-use guidance, no exclusions, and no alternatives from the sibling tool list, such as ingest_transcript_results.
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?
The annotations already flag this as non-read-only, non-idempotent, and destructive, so the description only needs to add context beyond that. 'Register your email' reinforces that it is a state-changing action, but it does not mention persistence, consent, unsubscribe behavior, or what happens after the email is registered. The feedback/connect framing also suggests capabilities not present in the schema.
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 appropriately short: two sentences front-loading purpose and then trigger guidance. Mild redundancy exists around 'feedback' and a minor inconsistency between 'Raven creator' and 'Raven team', but these do not seriously hurt clarity.
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 two-parameter registration tool with no output schema, the description is mostly adequate, but it leaves room for ambiguity. The most notable gap is that it invites feedback and connection intents despite no supporting input field being provided, and it does not clarify whether the tool simply registers an email or also starts a communication workflow.
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 fully documents both parameters with descriptions and an email format, so the description does not need to add parameter details. It adds little beyond singling out email as the key value; the phrase 'hold feedback' implies a message field that is not actually available in the input schema.
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 names a specific action ('register your email') and a clear outcome ('receive design updates and provide feedback'), which makes the tool's core purpose understandable. It does not explicitly compare itself to sibling tools like register_creative_asset, so sibling differentiation is only implicit.
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 provides an explicit trigger: 'Call this when a user wants to register, give feedback, or connect with the Raven team.' This gives clear guidance on when to use the tool, though it does not cover when not to use it or name 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 mark the tool as destructive and non-idempotent, and the description adds useful behavior: overlay injection, loopback serving, and proxy-mode behavior. However, it does not disclose lifecycle implications beyond starting — such as how long the background bridge runs, whether it is persistent, or that a running server session is created.
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 short — two sentences with strong front-loading of the primary action. The phrasing is economical, though terms like 'capability-keyed', 'Raven', and 'zero-paste' add flavor without substantial precision.
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 lack of an output schema and the operational nature of this tool, the description misses some contextual grounding: what a grab bridge concretely does, what start/stop lifecycle expectations are, and whether the bridge runs in a foreground process, background session, or as a service. The proxy mode and manual script alternative are covered, but the tool's operational footprint is not fully surfaced.
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 is fully documented at 100% coverage, so parameters like path, port, mode, and proxy_target already carry clear meaning. The description does not add meaningful parameter-level guidance beyond echoing the proxy/manual mode distinction found in the schema.
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 names a specific action and resource — 'Start a capability-keyed Raven grab bridge on loopback' — and explains the two main modes (proxy and manual script tag). However, 'Raven grab bridge' and 'capability-keyed' are unexplained jargon, and the description does not explicitly contrast with stop_grab_session or other grab-related siblings.
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 recommends proxy mode as the 'preferred zero-paste path' and notes the manual script tag remains available when needed. This gives clear within-tool routing guidance, though it does not state when proxy mode is not appropriate or explicitly point to stop_grab_session for teardown.
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 destructiveness and read/write hints, so the agent is warned that this is not a pure read operation. The description does not contradict the annotations, but it also does not explain why a 'get' operation is flagged destructive or what exactly may happen to the graph when the node is fetched.
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 compact sentence that puts the verb and resource first and contains no redundant filler. Every word contributes to the meaning of what the tool returns.
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 does state the main output shape: the node and all nodes connected to it by edges in either direction. But there is no output schema, so the agent still lacks detail about how edges, directions, or node data are returned, and the destructive annotation is left unexplained.
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 only parameter is fully described by the schema: id is the Decision Graph node id. The description adds only the slight extra meaning that id is the starting node from which connected nodes are followed, so it has limited additional value.
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 names a concrete operation ('Get'), a specific resource ('a Decision Graph node'), and a clear output shape ('every node connected to it by an edge in either direction'). It is specific enough to distinguish the tool from the many decision_* siblings without needing to inspect their schemas.
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 the agent needs a decision graph node and its graph-connected neighbors. However, it does not explicitly state when to prefer it over closely related sibling tools such as decision_list or decision_history, nor does it give any excludes or 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 signal mutation and destructive potential, and the description adds meaningful state behavior: 'Applied/rejected/superseded changes leave the pending set.' This goes beyond the structured hints by describing side effects on the pending set and reinforcing that the tool can update/mark, not just read. It does not fully spell out destructive consequences, but it exceeds the baseline.
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 compact and front-loaded: it quickly enumerates the tool's modes in one sentence and then adds state semantics in a second. No filler or redundant restatement of the tool name is present. The sentence is a bit dense because it packs three modes, but every clause adds needed distinction.
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 multi-mode tool with three optional parameters and no output schema, the description conveys the key invocation branches and observable state effects. Combined with the schema, an agent can understand read/update/list/batch usage. The lack of any statement about return shape or result format is the most noticeable gap, but not enough to make the description inadequate overall.
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 property descriptions cover 100% of the three parameters, so the baseline is a 3 per the rubric. The description's terms 'durable', 'legacy', and 'unified batch' align conceptually with operation_id, mark, and batch, but they do not add meaningful new semantic detail beyond 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 names distinct verb+resource pairs: 'read or update one durable grab change', 'list legacy reorder operations', and 'request the unified style+reorder batch'. This clearly distinguishes the tool from related siblings like get_grab_layers and get_grabbed_elements by adding scope terms like durable, legacy, and unified batch.
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 explains what the tool can do but does not give guidance on when to choose this tool over alternatives, nor does it provide exclusions. Phrases like 'legacy reorder operations' hint at a usage context, and schema constraints mention combinability, but the description itself leaves when-to-use versus siblings 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry destructiveHint=true and idempotentHint=true, so the description is not required to restate those. It adds the source-selection behavior not visible in the schema, but it does not disclose what gets destroyed or whether an existing DESIGN.md is overwritten. The description does not contradict 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 one tight sentence, front-loads the main action, and communicates the essential source modes with no filler. Every phrase 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?
The description is reasonably complete for a 2-parameter initializer, but gaps remain around the optional 'from' parameter's default behavior and the destructive effect on an existing DESIGN.md. With no output schema and no explicit overwrite semantics, an agent is left to infer these details from annotations alone.
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 both 'from' and 'path' are already documented in the schema. The description adds a bit of extra context by naming the specific source options, but it does not meaningfully compensate for or clarify anything beyond the schema's own 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 names the verb 'Initialize,' the target resource 'DESIGN.md,' and the supported sources: a stored Raven token system, a getdesign.md starter slug, or a blank template. This distinguishes it from sibling tools like read_design_md and update_design_md without needing to inspect their schemas.
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 this tool is used (creating/initializing a DESIGN.md) but does not explicitly state when to prefer it over update_design_md or read_design_md, nor does it list exclusions. The source options give some context, but there is no explicit when-not or alternative 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?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe query nature is covered. The description adds the 'local' scope as behavioral context, but it discloses nothing else such as return shape, pagination, or ordering. It neither contradicts nor meaningfully extends 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 front-loaded sentence with no filler. Every word contributes: 'List' specifies the operation, and 'local Raven creative brand profiles' identifies the exact resource 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?
For a simple zero-parameter read-only list tool, this description is nearly complete. The only missing detail is what kind of entries the list returns or how the 'local' scope is defined, but given the low complexity, the description is adequate.
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, so the description does not need to explain parameter semantics. The baseline for a zero-parameter tool is 4, and the description is consistent with that.
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 a specific verb 'List' with a clear resource, 'local Raven creative brand profiles.' It is clear enough to distinguish from sibling list tools like list_taste_profiles and list_creative_models, though it does not explicitly contrast with get_brand_profile or create_brand_profile.
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 implied usage is that this tool enumerates brand profiles, but the description gives no explicit guidance on when to choose this over get_brand_profile, create_brand_profile, or other list tools. Context is minimal and relies on the tool name and the verb '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 provide readOnlyHint=false, idempotentHint=false, and destructiveHint=true. The description adds meaningful nuance by stating the side effect is optional and that jobs are draft generation jobs, which conveys uncertainty and safety beyond bare mutation hints. It still doesn't describe the exact output and lifecycle of those jobs.
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 filler: the first sentence names the primary action and optional side effect; the second sentence enumerates the workflow scope. The structure is scannable and front-loaded, making it easy for an agent to quickly understand the tool's domain.
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?
With 10 parameters, no output schema, and optional job creation, the description doesn't tell the agent what the tool returns—whether it returns a plan document, job IDs, a confirmation, or a list of drafts. The workflow list is helpful, but missing return/umbrella context requiring the agent to search elsewhere.
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 baseline is 3. The description does not add any parameter-level meaning; it repeats the create-job concept that is already in the schema's create_jobs field and does not clarify how variants_per_format, formats, or source_asset_ids play together.
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 states a specific verb-resource pair ('Plan... campaign') and enumerates concrete workflows (product photos, UGC/video ads, marketplace cards, etc.), making the core purpose clear. It does not explicitly differentiate itself from the sibling create_generation_job, especially since it can also create draft generation jobs, so it falls just short of a 5.
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 workflow list implies when the tool should be used, but there is no explicit 'use this when' or 'use create_generation_job for single jobs' sentence. An agent can infer that this is for campaign-level multi-asset planning, but the boundary with single-job generation tools is left to reasoning.
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 destructiveHint=true and readOnlyHint=false, and the description adds useful behavior beyond that: if execute=true and RAVEN_CREATIVE_RUNNER is configured, the job is submitted to that runner. It also tells the agent that a 'brand-aware provider payload' is returned, which is extra useful 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?
The description is concise: three sentences that front-load the core purpose and then provide return type and conditional behavior. There is no fluff or redundant restating of the schema.
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 a large 15-parameter surface and no output schema, the description covers the main decision factors: what kind of jobs it supports, what it returns, and when an execution side effect occurs. It could still mention the exact shape of the returned payload or what happens when execute=false, but it is adequate for a capable agent to proceed.
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 already documents 100% of the 15 parameters, so the description doesn’t need to go through each one. It adds some context around media types and the execute/runner flow, but it does not introduce new meaning to individual fields.
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 states a specific verb ('Create') and resource ('a Raven creative generation job') and lists the covered media types (image, video, 3D, audio, campaign, analysis). It clearly separates from retrieval siblings like get_generation_job and list_generation_jobs, though it does not 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a new Raven generation job is needed and overlays the execute=true/RAVEN_CREATIVE_RUNNER condition. However, it does not explicitly provide when-to-prefer-this tool versus related siblings such as plan_creative_campaign, score_creative, or list_creative_presets.
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, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is covered. The description adds context about complete lineage and chronological ordering, which is useful but not extensive. 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 a single focused sentence with no filler. The core behavior is front-loaded, and the ordering detail is placed efficiently without redundancies.
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?
This is a simple read-only tool with one well-documented parameter and no nested schemas. The description adequately explains what the tool does and its output ordering. It could mention what shape the lineage takes, but given the low complexity, 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 description coverage is 100% and the 'id' parameter is already well-documented as an existing decision id anywhere in the lineage. The description adds no meaningful parameter semantics beyond what the schema provides, so the 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?
The description uses a specific verb ('Return') and identifies the resource ('complete supersession lineage for a decision') with ordering detailed. This clearly differentiates it from siblings like decision_get or decision_list, which focus on individual decisions or lists, so an agent can tell them apart.
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 makes clear the tool is for retrieving the full lineage of a decision, but it does not explicitly state when to prefer it over alternatives such as decision_get, decision_list, or decision_evidence. The context is implied rather than explicitly articulated.
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 presents an apparently read-only listing operation, but the annotations declare readOnlyHint:false and destructiveHint:true. The description does not mention this destructive character or any side effect of listing decisions. This is an Annotation 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?
The description is compact and front-loaded, with every sentence adding useful guidance. The semantic explanation of 'contested' status and the final heuristic about missing decisions are both purposeful, not 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?
The description makes the core selection semantics clear, including the non-obvious contested-decision behavior. It does not describe pagination, sort order, or exact return shape, but the operation is simple enough that 'list decisions' implies a list return, and the parameter schema covers the optional knobs.
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 four parameters already have schema descriptions, so the baseline can be 3. The prose adds meaningful interpretation by explaining why contested decisions are excluded from the default and how to opt into seeing them. It does not deepen drafts_only/include_candidates, but the schema already covers those.
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 opens with a specific verb and resource: 'List decisions in the local Decision Graph.' It immediately clarifies the default scope (ACTIVE decisions only) and defines what 'active' means — decisions that currently govern — which distinguishes this listing tool from single-decision tools like decision_get.
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 gives explicit guidance on how to adjust the default behavior: omit status for active decisions, pass status:'contested' to review disputes, or use include_contested:true to see both. It does not compare against sibling decision tools, but it does clearly explain the main filtering alternatives and the contested-decision rationale.
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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false). The description adds value by indicating what content the tool returns and how filtering works, but it does not disclose return shape, pagination, or any other runtime behavior. 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 a single, front-loaded sentence that names the resource, gives concrete content previews, and describes the optional filter. Every part earns its place with no redundant language.
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-only tool with two optional parameters and no output schema, the description gives enough context about content and filtering. It is slightly generic with 'and more', and it doesn't mention how 'format' changes the output, but the schema fills that gap. Overall complete but not maximally thorough.
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 both 'format' and 'context'. The description reinforces the contextual filter with additional examples like 'form labels', but the schema already carries most of the parameter meaning, so the value added is slight.
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 names the verb ('get'), the resource ('UX-writing principles'), and enumerates the actual content areas ('clarity over cleverness, active voice, error-message anatomy, inclusive language, voice vs tone'). This makes it easy to distinguish from generic sibling tools like get_principles or get_content_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 use for UX-writing guidance and explains how to filter by context, but it does not explicitly say when to choose this over siblings such as get_principles, get_content_pattern, or get_content_system. There is clear context but no exclusions or alternative routing.
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?
The description adds one useful behavioral detail beyond annotations: candidates are created in a non-confirmed, reviewable state. However, since `destructiveHint` is true and `idempotentHint` is false, the description does not clarify what may be destroyed, overwritten, or what happens on repeated invocations.
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 short sentences with no filler. The core behavior is front-loaded, and the important 'Nothing is auto-confirmed' caveat is presented separately and clearly.
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 two-parameter tool with complete schema descriptions and annotations, the description captures the essential transformation and resulting state. It is nearly complete, though it does not mention return behavior, validation failures, or downstream review workflow details, which would improve clarity 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?
The input schema already documents both `source_id` and `extraction_json` with descriptions, so the baseline is 3. The description reinforces that the JSON is model-produced and that candidates link to a source, but it adds no additional format, validation, or edge-case 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 states the action (parse), the input type (model-produced extraction JSON), and the result (reviewable Decision Graph candidates linked to source). It clearly distinguishes this from a confirmation/commit action with the caveat 'Nothing is auto-confirmed.'
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 usage context is implied: the tool should be used when model-produced extraction JSON needs to become reviewable candidates without auto-confirmation. However, it does not explicitly name alternative tools such as `ingest_transcript`, `decision_import`, or `decision_commit`, nor does it give a direct when-not-to-use condition.
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?
The annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds that entries include typical inputs and best-for guidance, which is useful output-context, but it does not disclose anything beyond that: no auth expectations, no rate-limit behavior, no pagination/syncing behavior, and no data consistency caveats. Given the existing annotations, a 3 is reasonable.
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 tightly packed, three-sentence structure with the verb and resource first, then scope, then the useful output shape. Every sentence adds new information, there's no filler, and it reads naturally for an agent scanning tool descriptions.
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 a simple tool with two optional, 100%-documented parameters and no nested objects, the context is mostly complete for listed use. The description hints at return value details by saying 'each entry lists typical inputs and best-for guidance,' which largely compensates for the absence of an output schema. The final remaining gap is lack of a more explicit pointer to sibling listing tools for different contexts (e.g., list_creative_presets), so a knowledgeable agent can select the best alternative.
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 baseline is 3. The description's references to image, video, 3D, audio, and analysis align conceptually with the media_type enum, but do not meaningfully extend the schema's per-parameter meaning. The description frames the tool as browsing catalog entries and does not add explanatory detail about the capability parameter's set of accepted values beyond what the enum and examples already provide.
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 ('Browse') and names a distinct resource: Raven's provider-agnostic creative model catalog. It also scopes the catalog to capability slots for image, video, 3D, audio, character consistency, and creative analysis, which clearly differentiates this from sibling list tools like list_creative_presets or 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys clear context: this is for surveying creative model capability slots and each entry provides typical inputs and best-for guidance. However, it gives no explicit 'when to use this vs. alternatives' signals, such as 'use list_creative_presets when you need ready-made presets' or examples where this tool is not appropriate. Usage is strongly implied by the catalog framing but never made 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is clearly safe and non-mutating. The description adds the 'local' scoping qualifier, which is useful, but it does not disclose further behavior such as default ordering, pagination behavior, or whether the list is limited to the current session. Given that annotations already carry the key safety traits, a 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 a single, short sentence with no filler. It states exactly what the tool does in the fewest possible words while still including the important 'local' scope qualifier.
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 list operation with all parameters documented and annotations covering idempotency and read-only behavior, the description is mostly sufficient. The only minor gap is that it does not mention what the returned list contains or whether results are paginated, but since there is no output schema and this is a straightforward list action, the current level of detail is nearly 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?
The input schema has 100% description coverage: each parameter (limit, status, media_type) has a clear description and type. The description itself does not need to repeat parameter details. The baseline 3 applies because the schema does the heavy lifting and the description adds no extra parameter guidance beyond that.
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 ('List') and a specific resource ('local Raven creative generation jobs'), making the operation unambiguous. The scope qualifier 'local' and the domain qualifier 'Raven creative generation' help distinguish it from the many sibling tools, particularly get_generation_job and 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?
The verb 'List' implies this tool is for enumerating jobs rather than retrieving or creating one, but the description does not explicitly state when to prefer this over get_generation_job or create_generation_job. The usage context is inferable from the name and siblings, but no direct guidance or exclusions 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered without description. The description adds the 'local' scope, but otherwise does not detail any additional behavioral traits such as return format, not-found handling, or caching. It does not contradict 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 front-loads the verb and resource. There is no extraneous detail, and every word contributes to the tool's core 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 simple read-by-id tool with one well-documented parameter and strong readOnly/idempotent annotations, the description is sufficient to allow correct invocation. It explains what the tool reads and how to identify the target, and the lack of an output schema is not a major gap for a straightforward read operation.
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 'id' parameter, and the schema already describes it as 'Brand profile ID.' The description adds 'by ID,' which restates the parameter usage without introducing any new semantic detail. This matches 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 uses a specific verb ('Read') with a specific resource ('local Raven creative brand profile') and explicitly states the access method ('by ID'). This clearly differentiates it from siblings like list_brand_profiles or get_brand_system, though it does not name them directly.
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 intended usage is implied by the phrasing 'Read a local Raven creative brand profile by ID' — a single profile lookup rather than a list or mutation operation. However, it does not explicitly state when to use this tool over alternatives, such as list_brand_profiles for retrieving all 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 convey readOnly, idempotent, non-destructive behavior, so the description wasn't required to repeat them. It adds that the result is a list of yes/no verification items, which is useful, but does not clarify whether the checklist is a static, pre-defined list vs. generated from the current design state.
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 sentences that front-load the tool's purpose, resource, and output shape. Every word earns its place with no repetition of annotation or schema content.
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 lookup tool with full schema coverage and supporting annotations, the description gives an agent everything it needs to call the tool correctly: what type to provide, why optional platform context matters (via schema), and what to expect back.
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 already describes all parameters: 'type' has clear examples and 'platform' has an enum plus platform-specific guidance. The description adds no new parameter semantics, so this sits at the schema-coverage 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?
States a specific verb and resource: 'Get a pre-publish checklist for a specific UI type' and clarifies what the caller receives ('actionable yes/no items to verify before shipping'). This distinguishes it from sibling audit and evaluation tools, which analyze existing pages rather than return a type-driven checklist.
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 this is the right tool when you need a pre-shipping checklist for a known UI type, but it never explicitly contrasts it with sibling tools like audit_page, evaluate_design, or get_page_template. There is no 'when not to use' guidance, so the agent must infer the boundary.
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 the read-only, idempotent, non-destructive profile, which matches the description. The description adds resource context but does not disclose other behaviors like error responses or whether the job may be returned partially. With annotations covering the safety aspect, a 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?
A single, well-structured sentence that front-loads the action and resource with no redundancies. Every word 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?
This is a simple one-parameter read operation with no output schema and robust annotations. The description is complete enough to guide invocation behavior—knowing the tool retrieves a single generation job by ID. Any additional detail about return payloads would be redundant here.
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 describes the only parameter 'id' as a generation job ID with 100% coverage. The description merely reinforces 'by ID' and does not add extra value beyond 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 uses a specific verb, 'Read', with a clear resource, 'Raven creative generation job', and specifies the identifier dimension 'by ID'. This cleanly distinguishes it from sibling tools like create_generation_job and list_generation_jobs, which imply different scopes and actions.
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 ID, but it does not explicitly state when to prefer this tool over alternatives such as list_generation_jobs or create_generation_jobs. The guidance is only implicit through the word 'by ID', and no alternatives 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?
The annotations already convey that this is read-only, non-destructive, and idempotent, so the description does not need to restate that. It adds the useful detail that the result includes provenance, but it provides no additional operational information such as ordering, pagination, or absence of filtering; the behavior section is adequate but not enriched.
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, front-loaded with the verb 'List,' contains no filler or repetition. Every word contributes to scope and result semantics, making the description quick and inexpensive for an agent to parse.
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?
The tool is a simple read-only list operation with one optional constant-valued parameter and no output schema. The description names what is returned, the scope, and the existence of the parameter default via the schema. There are no missing practical details that would prevent an agent from invoking the tool 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?
The schema has 100% description coverage: the only parameter, baseline, is already documented with its constant value raven-canonical and its default behavior. The description mainly repeats the canonical-baseline idea without introducing new parameter-level meaning beyond what the schema already gives.
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 the specific verb 'List' with a concrete resource, 'components and provenance', and narrows the context to the 'Raven canonical baseline.' This is enough for an agent to distinguish the tool from sibling tools that list design systems or inspect individual design-system elements.
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 intended usage is implied: call this tool to discover the components and provenance in the canonical Raven baseline. However, the description never explicitly contrasts it with the many related design-system tools, such as get_design_system, list_design_systems, or inventory_design_system, so the agent receives no explicit when-not-to-use 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?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds real value by disclosing that 'permissions and allowedTokens are advisory metadata' and not enforced, preventing the agent from treating returned labels as authoritative restrictions.
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 every sentence earns its place: the first states the operation and scope, and the second warns about the advisory nature of returned metadata. There is no filler or redundant wording.
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 zero-parameter, read-only listing tool, the description covers the main things an agent needs: what is listed, where it comes from, and what semantics to apply to the returned metadata. It does not mention what happens when no active grab session exists, but the description is otherwise 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 tool has zero parameters and the schema covers all of them, so there is no parameter documentation gap to compensate for. The description's active-grab-session scoping is contextual, not parameter guidance, making the zero-parameter baseline the right choice.
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 opens with the verb 'List' and clearly names the resource: templates and their registered page pathnames from the active grab session. This is a specific, clear operation. It does not explicitly differentiate itself from nearby siblings like get_page_template, though the plural 'List' and 'registered pathnames' imply a broader listing.
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 phrase 'from the active grab session' gives a meaningful scoping cue and implies the tool is meant for sessions started with start_grab_session. However, no explicit when-to-use or when-not-to-use guidance is provided, and no alternative tools are named. Usage is mostly implied rather than directly instructed.
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 convey that the operation is not read-only, is destructive, and is not idempotent. The description adds a meaningful extra behavioral fact: Raven stores metadata and a URI/path, not the actual file bytes. It does not elaborate on destructive side effects, but that risk is already exposed by 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 focused sentences. The core action is front-loaded, and the meaningful caveat about storing metadata instead of bytes is expressed economically. There is no filler or redundant restating of the tool name.
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 tool with six parameters, a nested metadata object, and no output schema, the description covers purpose and storage semantics well but does not explain what the operation returns or what a successful registration causally changes. Since there is no output schema to rely on, that is a significant gap.
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 every parameter, including required `uri` and `type`, is already documented structureally. The description reinforces 'uri/path' and 'local or remote' but does not add meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (register), resource (creative asset), and intended context (Raven jobs), and even explains the key distinction from upload: only metadata and a URI/path are stored, not file bytes. It does not explicitly differentiate against the large sibling tool list by name, so it falls just short of maximum clarity.
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 'local-first analog of upload' sentence gives the agent a practical usage signal: choose this when the asset should be represented by metadata and a URI/path rather than uploaded bytes. It does not explicitly spell out when to use upload instead or name sibling tools as alternatives, but the context is clear enough to guide basic 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?
Given the annotations already declare readOnlyHint=true and idempotentHint=true, the description adds behavioral value by enumerating exactly what is analyzed and how the input should be captured. It makes clear this tool consumes ready-made snapshot data and does not generate it, which is useful behavioral context beyond the safety 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 compact and well-structured: it opens with the action, then summarizes the audit checks, and closes with the exact input shape and capture mechanism. The inline list is a little long, but each part carries operational meaning and there is no filler or repetition.
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 nested complex schema with no output schema or param descriptions, the description covers the main input contract exceptionally well but leaves gaps: no description of return/output format, no explanation of the 'options.minTarget' field, and no units for colors or fields. These omissions leave an agent needing to guess some behavior despite the otherwise rich scaffold.
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 description explicitly lists the main required fields (elements, viewport, and the nested element attributes) and therefore gives useful semantics for the core parameters. However, the optional 'options' parameter and its 'minTarget' field are completely unexplained, and there are no descriptions inside the schema, so the tool doesn't provide complete parameter-level guidance.
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 operation: 'Score an accessibility-enriched iOS element snapshot' followed by the specific audits it performs (missing labels, tap target sizes, WCAG contrast, Dynamic Type clipping, VoiceOver order). This is specific enough to distinguish it from sibling audit tools such as audit_ios_screen or audit_contrast even without their schema.
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 clearly indicates it should be used when an accessibility-enriched element snapshot is available and refers to the capture method ('via the AccessibilitySnapshot XCUITest / ios-capture harness'). It does not explicitly name alternative tools or state when not to use it, but the specific resource and capture requirement make the use case evident.
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 the tool read-only and idempotent, so the safety profile is covered. The description adds meaningful behavioral context beyond that: specific violations that get flagged (font sizes below ~13pt, empty AccentColor, sub-44pt frames, off-grid spacing), the 'Rewards...' scoring behavior, and the output contract ('pass/fail per check with fix instructions').
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 tight paragraph that front-loads the action, packs the check list into compact parenthetical clusters, tacks on the scope restriction, and ends with the return contract. Every clause earns its place — around 70 words with zero filler, repetition, or marketing 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?
Given the moderate complexity and no output schema, the description adequately covers the return shape ('pass/fail per check with fix instructions') and the main behavioral surface. The optional profile/project binding and strict-mode grading semantics are carried by the 100%-covered schema, so nothing critical needed to invoke the tool correctly is missing.
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 each of the 5 parameters already has a rich description (source concatenation, strict-mode semantics, taste-surface binding, accent_color_contents verification). The tool description adds only one cross-reference — tying the accent_color_contents parameter to the empty/undefined AccentColor check — which is useful marginal context but not compensating work, so the 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?
The description uses a specific verb ('Audit') with a specific resource ('SwiftUI source') and a named standard ('Apple's Human Interface Guidelines'), then enumerates the exact rule categories checked. It also distinguishes itself from sibling audit tools by declaring 'iOS-native checks only — no web/CSS rules'.
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 intended use context — SwiftUI iOS HIG auditing — is clear, and the exclusion 'no web/CSS rules' provides some boundary on when NOT to use it. However, none of the many overlapping audit siblings (audit_typography, audit_tap_targets, audit_contrast, audit_ios_a11y) are named, so when to choose this tool over an alternative is left to the agent's inference.
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 the operation as non-read-only and destructive, and the description meaningfully adds the concrete consequence: the decision stops governing immediately. It also discloses what does not happen, no deletion and no replacement requirement, reducing the risk of over-assuming side effects. It does not explain reversal or post-contest state, but the immediate behavioral consequence is well stated.
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 that front-loads the action and outcome, then adds two key exclusions. There is no filler, no repeated schema details, and no over-explanation. It earns high marks for conciseness and structure.
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 3-parameter destructive operation with annotations and a rich schema, the description gives the essential state information: contesting, active, stops immediately, no deletion, no replacement. It would be slightly more complete with an explicit note about the return value or resulting decision state, but the agent can safely call the tool with the provided information.
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, and each parameter already has a clear description including the graph-edge effect for evidence_ref. The tool description does not add extra parameter-level guidance, which is fine because the schema carries that burden. Baseline 3 is appropriate here.
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 ('contest') and resource ('active decision'), and states the concrete outcome: the decision stops governing immediately. It also distinguishes the operation from deleting or superseding by explicitly saying it does neither. This is enough to separate it from the many decision_* 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the correct usage: contest an active decision, especially when replacement is not intended. It provides a clear precondition ('active') and an implicit contrast with supersede, but it never explicitly names when to use this tool instead of decision_supersede, decision_evidence, or decision_commit. The usage guidance is present but left to inference.
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, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral detail by specifying exactly what kind of report is produced, what categories of drift are surfaced, and that output includes fix priorities. 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 one compact, front-loaded sentence. It starts with the core action and resource, then efficiently enumerates report contents without repeating schema details or including 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?
No output schema exists, so the description carries the burden of explaining return value: it lists report categories and says the result is scored with fix priorities. It does not explain required setup or output format, but since there are no required params and the setup is referenced by the schema, the description 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 description coverage is 100%, so the schema already documents all four params. The description mainly restates the general 'project/system vs baseline' concepts rather than adding new detail about platform, project_dir, or design_file_path 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?
Description uses a specific verb ('Diff'), names the resource (project's declared design system vs Raven canonical baseline), and lists concrete outputs (missing components/states/variants, token drift, fix priorities). It is clearly distinguished from sibling read-oriented tools by its comparison/diff intent.
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 use case is implied: use this tool when you need to compare a project design system against the Raven canonical baseline. However, it does not mention any alternatives or exclusion cases, so it relies on the agent inferring when other read/inventory/design-system tools might be better choices.
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 establish the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: matching is limited to 12 known design systems and returns the closest match with ready-to-use CSS. This sets realistic expectations about approximate matching, which is useful 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 compact, front-loaded, and every sentence earns its place: purpose, trigger example, and output expectations. It contains no filler or redundant explanation.
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?
There is no output schema, but the description explicitly names what the tool returns: full token set, style guide, implementation instructions, and ready-to-use CSS. It could add more on fallback behavior when no close match exists, but the core call context is covered.
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 100% parameter coverage, including enums, defaults, and examples. The description adds little beyond restating that CSS output is possible and showing a company example, so the schema carries the main semantic load.
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 a specific verb and resource: get a complete design system built around a specific company's branding, with a concrete example (Spotify). It clearly differentiates itself from generic siblings like get_design_system and list_design_systems by emphasizing company-matching branding.
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 a clear trigger phrase ('Say "Make me an app with branding like Spotify"') and describes what the tool returns. However, it does not explicitly explain when to prefer this tool over alternatives like get_design_system or what to do if the requested company is not among the 12 known 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?
The annotations already communicate readOnlyHint=true and idempotentHint=true, so the description does not need to restate safe read behavior. It adds valuable detail by listing the actual content returned, going beyond what the 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 one compact sentence, front-loaded with the action and resource. It lists the return contents efficiently and includes a purposeful application phrase without 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 read-only getter with one optional parameter and no output schema, the description adequately conveys what the tool returns and its intended context. It does not describe how the stage parameter changes the returned templates, but the schema enum and default value largely fill that gap.
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 fully documents the single parameter with an enum and a clear description, so the schema carries most of the load (coverage is 100%). The description does not add parameter-level semantics, but it does provide useful context about the template contents that complements the stage enum.
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 operation ('Get the D4D framework templates') and identifies the exact resource and contents it returns: customer problem statement, ideal state, hypothesis, LOFA, and experiment templates. This makes the resource unambiguous and helps distinguish it from other getter 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 phrase 'for structured product thinking' implies when this tool is appropriate, but it does not specify when to use it instead of similar knowledge resources such as get_principles, get_checklist, or get_research_method. No explicit alternatives or exclusions 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 signal read-only, idempotent, and non-destructive behavior. The description adds meaningful context by calling itself a 'transparent heuristic, not a proprietary prediction model,' which tells the agent what kind of logic to expect. This is genuinely beyond what the structured 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 dense sentences, no filler. The primary purpose and criteria are front-loaded, and the heuristic transparency note earns its place by setting expectations in one short clause. Every sentence contributes 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 absence of an output schema, the description could go a bit further by stating what the returned output looks like. However, the detailed list of scoring dimensions, the supported creative types, and the transparency cue cover most practical needs. It is almost complete for selecting and invoking the tool 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 parameters are already well-documented by the input schema. The description does not add deeper meaning for channel, audience, or brand_profile_id, but it does hint at how those parameters connect to the scoring dimensions. This meets the baseline for schema-heavy coverage without exceeding it.
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 names a specific verb and resource — 'Score a creative prompt, script, or ad concept' — and enumerates the exact scoring dimensions. This clearly distinguishes it from page-level and audit sibling tools without needing to name them. The criteria list leaves no ambiguity about what the tool does.
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: if you have a creative prompt, script, or ad concept and need scoring, use this tool. However, it does not explicitly state when not to use it or name alternative tools like score_page or audit tools, so the agent must infer selection boundaries from the resource type alone.
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, and the description adds valuable context beyond that: the tool navigates to and controls a LIVE external URL, fires hover/click/focus events, scroll-settles the page to trigger IntersectionObserver reveals and play videos, and requires headless chromium. It also discloses that findings are triaged into confirmed | likely-artifact | inconclusive with evidence, which shapes expectations about output quality. 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 dense but front-loaded, opening with the core mechanism ('render-and-capture audit... renders a LIVE URL') and building through pipeline, checks, output tagging, use cases, and the prerequisite. Every sentence earns its place and no filler is present for a tool of this complexity; it is long, but the richness justifies it.
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 no output schema, the description explains the result shape: findings with confirmed | likely-artifact | inconclusive tags, evidence, severity ranking, and per-capture data. It covers prerequisites, behavior, and use cases for a 9-parameter high-complexity tool with a live-URL dependency. The only small gap is what isn't mentioned — runtime expectations or error behavior — so nothing critical for an agent deciding to call it correctly is missing.
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 every parameter (url, themes, compact, timeoutMs, viewports, interactions, scroll_settle, containerMaxWidth, includeScreenshots) already carries its own meaning and defaults. The description adds pipeline-level color (e.g., why scroll_settle matters, why interactions exist) but does not add per-parameter detail beyond the schema — so the 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 names a specific verb and resource ('render-and-capture audit' of 'a LIVE URL') and describes exactly what the tool does: scroll-settles, fires interactions, captures pixels/DOM, then runs specific rule engines. It explicitly positions itself against the alternative class — 'invisible to HTML-string/geometry audits' — and even names the complete cases it catches, which distinguishes it clearly from the many 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 final sentence gives concrete when-to-use guidance ('catches real-world visual nits invisible to HTML-string/geometry audits') and lists examples: cropped images, blank videos, hover white-wash, sliced exports, hidden-on-mobile content. It also states a hard prerequisite (headless chromium). It doesn't name sibling alternatives like audit_page or audit_contrast explicitly as 'use these when...', but the exclusion direction 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?
It discloses that portraits are generated from the local taste store, are self-contained HTML, and that a portrait is a document about the surface—so design_notes are not acceptance criteria. This is useful context beyond what the annotations and schema provide. It does not describe exact overwrite behavior, but `destructiveHint: true` already covers the key side-effect signal.
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 three dense sentences with no filler. The main action and the gallery behavior are front-loaded, and the audit_taste caveat, while dense, is genuinely useful context for correct downstream usage. It is slightly long but 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?
For a file-generating tool with three parameters and no output schema, it covers the required inputs, both invocation modes, and the nature of the generated artifact. It could be more explicit about return values or confirmation behavior, but the expected output is well inferable from `output_dir` and the 'HTML portrait / gallery index' language.
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%; `profile`, `output_dir`, and the optional `project` behavior are already described in the input schema. The description reinforces the project/project-omit distinction in prose, but it adds little new parameter-level information beyond a paraphrase, so it sits at 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 opens with a specific verb and resource: 'Render a bound Taste Engine surface as a self-contained designed HTML portrait.' It clearly distinguishes the tool from sibling generation and audit tools, and it defines both output modes: one binding or every binding plus a gallery index.
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 gives explicit conditional usage: pass `project` to render one binding, or omit it to render every binding plus a gallery index. It also provides post-generation guidance around verifying with `audit_taste` and passing `document_kind:'portrait'`. It does not explicitly name alternative generation tools or state when not to use this tool, but the guidance is otherwise strong.
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 idempotentHint=true, covering the safety profile of the operation. The description adds no significant behavioral details beyond that (no return format, no requirement stipulations). No contradiction is present, so a neutral 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core resource and purpose, followed by a concise usage trigger sentence. The enumerated lists are dense but each item adds semantic nuance that the schema does not fully convey, so no sentence is wasted.
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 read-only, zero-required-params tool with no output schema, the description's identification of topics plus usage triggers is nearly complete. The gap would be an explicit differentiation from the closely related siblings get_principles and get_brand_system, which the description leaves implied rather than stated.
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 already covers 100% of parameters, but the description makes the topic parameter more meaningful by breaking it into concrete subtopics (clear space, min sizes, variants, palette, contrast, trend vs signature, etc.). This gives an agent higher confidence when choosing a filter value, which goes beyond the schema's generic 'filter by topic' statement.
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 a clear verb+resource: 'Get brand and visual-design principles' and then enumerates specific domains (logo usage, gradient usage, imagery, visual hierarchy, brand-as-system thinking). This immediately distinguishes it from sibling tools like get_principles or get_brand_system without requiring the schema.
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 an explicit 'Use when the user asks about...' sentence that lists concrete triggers (branding, logos, gradients, imagery, visual consistency). However, it does not explicitly name alternatives or mention when not to use this tool, e.g., how it differs from get_principles or get_brand_system.
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, idempotentHint, and destructiveHint=false. The description adds useful behavioral detail by stating the tool 'returns patterns, do/don't guidance, evidence, and a checklist,' making the response format predictable for the agent.
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 long with no filler. It front-loads the core action and resource, then immediately lists return contents and when to use the tool. 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 a one-parameter enum schema, readOnly/idempotent annotations, no nested objects, and no output schema, the description is complete. An agent can select this tool, choose the correct enum value, and invoke it with confidence based on the information provided.
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 already covers the single parameter `type` at 100% with a full enum and description. The prose mostly restates those enum values, though it adds 'recovery' as an alias for the moments-of-truth context. This is useful but does not substantially extend schema-provided meaning.
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 identifies the action ('Get'), the resource ('a service design pattern'), and enumerates the specific pattern types. It is clearly scoped to service design and therefore distinct from the generic sibling get_pattern, though it does not explicitly contrast itself with close siblings like get_service_standard or get_checklist.
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 trigger conditions: 'Use when the user is designing a service flow, escalation, cross-channel experience, or moment of truth.' It does not, however, say when not to use this tool or name alternatives for non-service design requests, so it lacks explicit exclusions or sibling routing.
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 adds behavioral context beyond annotations: it is append-only, existing records are never rewritten, and accept verdicts suppress matching findings in later audit_taste runs. This gives the agent important side-effect information that the annotations alone do not express.
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 compact and well-structured: it names the core action first, gives a concrete usage condition, and then spells out the most important behavioral consequences. There is no filler or unnecessary 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 mutation-like tool with 7 parameters and no output schema, the description covers the action, trigger context, important parameter nuances, and side effects. It does not describe expected return values, but that is less critical without an output schema, and the core execution context is complete enough for an 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?
Schema coverage is 100%, so the baseline is 3. The description adds valuable semantics for key parameters: wrong should be a verbatim snippet for suppression matching, and verdict meanings are clarified (accept suppresses, revise/reject confirm wrong). This goes beyond the schema's generic field descriptions.
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 states a specific action and resource: append a labeled precedent/verdict to a taste profile's corpus. It identifies the basic growth-loop function clearly, but does not explicitly differentiate itself from siblings like record_taste_decisions or audit_taste, relying more on the 'when to use' phrase.
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 to use the tool when a human accepts, revises, or rejects an audit_taste finding, or labels a new wrong→right example. This is strong guidance, but it does not mention when not to use the tool or name alternative tools for other 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?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds useful context by framing this as the ledger that evolves after the kickoff interview and by connecting it to record_taste_decision, but it does not describe operational details such as pagination or return 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?
The description is a single, front-loaded sentence with no wasted words. It conveys the resource, the action, the optional filters, and the relationship to another tool in a compact way.
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 list tool with one required parameter and two optional filters, the schema and annotations already handle most details. The description completes the picture by explaining the ledger's role in the kickoff interview process, making it a sufficiently complete definition.
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 profile, project, and dimension parameters already have clear meanings in the schema. The description mentions optional filtering but does not add anything beyond what the parameter descriptions already state.
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 opens with a specific verb and resource: listing taste/direction/design decisions recorded for a profile, and it names the related record_taste_decision tool. This clearly distinguishes it from generic profile or interview retrieval 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 conveys when to use the tool: to view the evolving decision ledger for a profile, optionally filtered by project or dimension. It points to record_taste_decision as the write counterpart, though it does not explicitly explain when not to use sibling tools like list_taste_profiles or get_taste_interview.
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 establish read-only, idempotent, non-destructive behavior. The description adds behavioral context beyond annotations: it returns 'a structured CI verdict with file/line findings and nearest-token suggestions' and it explicitly specifies that only added UI-code lines are reviewed. No annotation contradiction is present.
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, each with a distinct purpose: scope, return value, and call timing. There is no filler, and the most important information is front-loaded.
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?
Although there is no output schema, the description communicates the return value ('structured CI verdict with file/line findings and nearest-token suggestions') and the key inputs (DESIGN.md tokens, recorded decisions). Parameter schema fully covers the remaining configuration options, so nothing critical needed to call the tool correctly is missing.
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 fully documents all five parameters. The description adds minor context about added lines, but this is already represented in the parameter schema, particularly the diff-scoped behavior documented for fail_on. 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 opens with a specific verb ('review') and a clear resource ('added UI-code lines in a unified diff'), and names the comparison target ('DESIGN.md tokens and active recorded design decisions'). It also states the return shape ('structured CI verdict'). It stops short of a 5 because it doesn't explicitly name sibling alternatives or say what it is not.
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 gives an explicit invocation condition: 'Agents should call this on every PR or diff that touches UI code before merge.' This is clear usage guidance. It lacks explicit when-not-to-use guidance or alternative routing, so it doesn't earn a 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 mark the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it measures per-pixel luminance variance in the bottom strip and interprets uniform background as clean versus high-variance UI content as likely-sliced. This informs the agent about the mechanism and expected signal beyond the annotation flags.
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 well structured and front-loaded with the core detection purpose, then adds an example, method, and expected signal validity. Every sentence earns its place: no tautology, no repeated schema content, no filler, and the epsilon are kept at a useful detail level.
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 read-only, single-parameter audit tool, the description covers purpose, input, method, and result interpretation. The only gap is the lack of an explicit description of the return value shape, especially because there is no output schema; an agent would still need to infer whether the tool returns a pass/fail, a list of offenders, or report details.
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% because image_paths already has a clear description: 'Filesystem paths to PNG files to check for sliced/cut-off bottom content.' The tool description mostly restates this same idea, so it adds little parameter information beyond 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 leads with a specific verb and resource: 'Detect PNG exports whose content is sliced/cut off at the bottom edge.' It goes beyond the generic audit_* sibling pattern by naming the exact failure mode, giving an example (mid-form Figma export), and describing the per-pixel luminance method. This clearly distinguishes it from 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this when checking PNG files for bottom-edge slicing, especially cases where dimension/ratio checks would not catch the problem. It implicitly frames the alternative ('Dimension/ratio checks cannot catch cut content'), but does not explicitly name a sibling tool or state a hard when-not-to-use condition, so it stops short of a full 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to re-assert non-mutation. It adds valuable behavior beyond the annotations by stating that it flags contracting and always returns a BLOCK/PASS verdict.
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-load the action and scope, describe the contract shape, enumerate the bug classes, and state the verdict output. No word is wasted and no structured field is redundantly repeated.
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 gives adequate context: inputs, purpose, anomalous cases, and the BLOCK/PASS verdict. The main gap is mode-specific behavior for contract_spec, such as the difference between tokens mode and envelope mode, but the tool remains invokable as described.
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 0% schema description coverage, the description partially compensates by explaining that contract_spec represents token list/field set/schemaVersion and file_paths represents the N source files. However, it does not explain the mode enum tokens/envelope, the meaning and usage of schemaVersionPattern, or whether file_paths expects literal paths, globs, or directories.
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 names a concrete verb and resource: "Verify a wire contract ... is identical across N independent source files", lists the input families (token list / field set / schemaVersion), and enumerates the specific issue classes it detects. This clearly differentiates it from nearby audit tools like audit_api_contract, audit_parity, or audit_consistency.
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 intended use case is clear: cross-language wire contract consistency among iOS Swift, proxy JS, and Android Kotlin source files. It lacks an explicit when-not-to-use statement or named alternatives, so it does not hit a 5, but the context is still concrete enough for an agent to decide when to select 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?
The annotations already convey readOnly, idempotent, and non-destructive behavior. The description adds the useful mental model of mixing systems but not additional behavioral detail such as output shape, invalid pair handling, or system ID lookup behavior. 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 short and front-loaded: one sentence defines the purpose and one sentence provides a clarifying example. No redundancy or decorative wording.
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 full input schema coverage, robust annotations, and a clear format enum, the description is complete enough for an agent to select and invoke the tool. It could be marginally stronger by explicitly noting the output is a token composition or bundle, but nothing critical 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%, so the schema already documents the compositions array, system IDs, groups, and format enum. The description's example adds value by mapping a concrete use case to the parameter model: 'Linear's colors + Stripe's typography' translates directly to compositions pairs. It doesn't describe format further, but the schema already does.
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 a specific action ('Mix tokens from different design systems') and a concrete result ('create a custom composite'). The example 'Linear's colors + Stripe's typography' makes the resource and scope immediately clear, and distinguishes it from sibling tools like get_design_system or generate_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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: when combining tokens across independent design systems. It does not explicitly name alternatives or state when not to use it, but the combination-focused purpose is unambiguous enough 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?
Beyond the annotations, the description discloses that profiles are stored locally under ~/.raven/creative by default and that the tool both creates and updates profiles. This adds useful side-effect context. Nothing in the description contradicts the destructiveHint annotation; 'update' reasonably implies possible overwrite 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 short sentences deliver the action, resource, purpose, key stored fields, and the default storage location. There is no filler or repetition of annotations, and the primary statement 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?
Given full schema coverage, a single required parameter, and the absence of an output schema, the description is sufficient for an agent to invoke the tool correctly. It provides the storage default and purpose, though it could theoretically add more detail about update/overwrite semantics or the response shape.
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 has 100% description coverage for all parameters, so the schema already carries the semantic load. The description's field list mostly mirrors what the schema already documents rather than adding deeper parameter-level meaning. This is the expected baseline when schema coverage is high.
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 a specific action ('Create or update') and a clear resource ('local brand profile used by Raven creative jobs'), then lists what the resource stores. This makes it easy to distinguish from read/list siblings like get_brand_profile or list_brand_profiles, and from create_character_profile.
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 gives clear context: this is for creating or updating a local brand profile for Raven creative work. It does not explicitly name alternatives or state when not to use it, so it stops short of the strongest possible guidance, but the intended context is still 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 a write operation and destructive potential. The description adds non-obvious context by explaining that Raven only stores reference asset IDs and provider-training payloads locally, and that no actual identity training occurs in this step. It does not detail overwrite behavior for existing profiles, but the destructive hint covers that signal.
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 the core action front-loaded and the key scope boundary clearly stated in the second sentence. No wasted words or redundant restatement of the schema.
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, combined with 100% schema coverage and annotations, gives an agent enough to understand the tool's purpose, side effects, and limitations. The only notable gap is the lack of any statement about what the call returns, such as the created profile ID, but the optional stable id parameter partially mitigates 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?
Schema description coverage is 100%, so parameters are already well documented. The description adds slight context by connecting reference_asset_ids and provider-training payloads, but it does not materially expand on the schema's per-field descriptions. 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?
Opens with a specific verb and resource: 'Create a local character/identity reference profile for consistent image or video generation.' This clearly distinguishes it from siblings like create_brand_profile and create_taste_profile, and clarifies it is creating a local reference profile rather than a trained identity.
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 makes the main use case clear: create a local profile for consistent image or video generation. It also explicitly excludes the major confusion point: 'actual identity training happens only through a configured provider runner.' It does not name sibling tools, but the boundary is clearly drawn.
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 cover read-only, idempotent, and non-destructive; the description adds genuine behavioral value by revealing the quiet digest mode and the actionable:false no-op contract. That sort of runtime behavior goes beyond what readOnlyHint and idempotentHint can convey, so it earns credit.
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 states exactly what the tool scans for, the second instructs the scheduler how to call it and interpret the result. It is front-loaded and every phrase 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 read-only, idempotent scan with hand-documented parameters, the description plus schema is sufficient to invoke the main flow correctly. The only gap is the full shape of an actionable=true report — no output schema exists—but the description does enough to make the tool safely callable.
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 each parameter already explains itself: digest_only describes a hands-off quiet mode, reference_systems gives its registry fallback behavior, and use_cases defines the coverage term source. With full schema coverage the described baseline of 3 is correct.
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 a specific verb ('Scan') and a specific resource ('the local Decision Graph'), then itemizes exactly what is detected: uncovered components, weak rationales, contested decisions, and derived staleness. This level of detail, along with the unique resource, cleanly separates it from sibling scan/audit tools like talon_scan.
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 gives explicit guidance to its main caller class ('Schedulers should call with digest_only:true') and clarifies the expected result ('treat actionable:false as a no-op'). It does not name alternates or state when this tool should not be used, but the intended invocation 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 flag the tool as non-read-only and potentially destructive, so the bar is lowered. The description adds useful behavioral context: save:true writes to the design system storage, id collisions are refused, and HTML output is self-contained. This goes beyond the 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 three purposeful sentences: core purpose and formats, value of the HTML export, and the save/reuse decision. Information is front-loaded and no sentence is 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 7-parameter generation tool, the description covers the main decisions: the inputs to provide, the export choices, the HTML output quality, and when to persist. It does not fully describe return structures for each format, but the schema is rich and the key invocation behavior is disclosed.
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 baseline is 3 even without detailed description prose. The description adds some param-level flavor, such as a brand color auto-generating a palette and save:true enabling durability, but most of the param meaning already lives 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 uses a specific verb and resource: 'Generate a complete, custom design system with full token set.' It clearly distinguishes this creation-focused tool from retrieval-oriented siblings like get_design_system and list_design_systems, and it names the core deliverables and inputs.
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 makes the core usage scenario clear, especially around persistence: passing save:true is how a design system becomes durable and reusable by id. It does not explicitly enumerate alternatives to avoid, but it gives enough contextual guidance to select this tool over the retrieve/list 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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context by detailing the content delivered and noting results are 'matched to' the design context, suggesting selection/filtering 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 tight sentence that front-loads the purpose before enumerating the returned principle types. Every phrase earns its place: no filler, no repetition, and no redundant restatement of the tool's name.
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, combined with a fully-documented schema and safe-read annotations, gives an agent enough to select and invoke the tool. It lacks an explicit statement about the platform/category substitutions, but those are fully captured in the schema descriptions, so this is not a material gap.
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 descriptions already define context, format, category, and platform adequately. The description's first sentence reinforces the 'context' parameter concept but does not need to add more; baseline 3 is appropriate given 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 names a specific verb and resource: 'Get design principles' for a UI context, and enumerates the types of content returned (heuristics, UX laws, Gestalt, accessibility, typography, color). This distinguishes it from sibling tools like get_content_principles or get_brand_principles, whose scopes differ.
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 clearly establishes when to use the tool: for a UI context, matched against what you're designing. It does not explicitly name sibling alternatives or state exclusions (e.g., when to use audit_* or evaluate_design instead), which keeps it at a 4 rather than a 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 mark this as readOnly, idempotent, and non-destructive, which covers the safety profile. The description adds meaningful behavior: it returns a browsable list of available systems, applies optional filters, and treats 'user' as a category for saved personal systems. It does not mention pagination or ordering, but for a listing tool the annotations plus filter semantics are strong.
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 filler. The first sentence states core purpose, the second enumerates valid filter values. It is front-loaded and every clause adds 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?
This is a simple read-only list tool with fully documented optional parameters, an idempotent/read-only annotation, and no output schema. The description is complete for deciding whether and how to invoke it. Slightly more context about what fields each returned item contains would push this to a 5, but it is not necessary for correct 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 description coverage is 100%, so the schema already documents both parameters fully. The description repeats the category filter set and adds the 'search' semantics, providing marginal value over the schema without needing to compensate.
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 names a specific verb ('list'), a resource ('design systems'), and the available filters ('category' and 'search'). It clearly distinguishes itself from the related sibling 'get_design_system' (singular fetch vs. plural browse) and 'list_design_system_components' (a different resource).
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 makes the core use case explicit—browsing available design systems before selecting one—and spells out the two supported filtering modes. It does not explicitly state when one should use get_design_system or list_design_system_components instead, but the intent to enumerate available systems is unambiguous.
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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds no additional behavioral details beyond the search scope, such as how results are ranked or returned. Given the annotation coverage, this is acceptable but not especially informative.
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 short sentences, front-loading the core function in the first sentence and giving usage guidance in the second. No filler or redundancy, and every clause contributes to helping the agent decide when to use this tool.
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 read-only search tool with two simple parameters and full schema descriptions, the description is nearly complete. It explains scope and usage context but stops short of describing output shape or how to interpret results, which an output schema would normally handle. Given no output schema exists, a small gap remains, but the tool is simple enough that this is not a serious risk.
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 parameters are already fully documented with examples. The description reinforces the meaning of the `layer` enum by naming the categories (principles, patterns, business) that match the enum values. It does not contradict the schema and adds slight contextual meaning without needing to compensate for 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 specifies the exact action ('Search') and the full resource scope ('all design principles, UI patterns, and business strategies'), distinguishing it from category-specific siblings like get_principles or get_pattern. The phrase 'or don't know which category to look in' helps an agent understand this is the cross-cutting discovery tool, not a targeted one.
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 gives an explicit when-to-use signal: use it when you need specific guidance or are unsure of the category. It implies the alternative is using category-specific getter tools when the category is known, though it does not name them directly. This is clear context but not a fully explicit when-not-to-use statement.
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 this tool as destructive and idempotent. The description adds value by specifying that it stops the active bridge and clears its queued selections, making the specific state-change explicit beyond the generic annotation hints.
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, tightly worded sentence that front-loads the primary action and appends the secondary side-effect. Every word contributes meaningful information with no waste.
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 zero-parameter, no-output-schema tool, the description captures the full operational effect of stopping the grab bridge and clearing queued selections. It could add notes about whether the session is permanently closed or what happens to already-captured references, but given the tool's simplicity, the description is adequate.
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 zero parameters and the input schema is empty, so there is nothing for the description to clarify. This meets the baseline expectation for parameter-less tools, even though no additional parameter notes are provided.
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 ('Stop') and a precise resource ('current grab bridge') plus a concrete action ('clear its queued selections'). This clearly differentiates the tool from siblings such as start_grab_session and get_grabbed_elements.
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 phrase 'current grab bridge' implies the tool should be used when a grab session is active, and the 'clear' action signals a terminal step. However, it does not explicitly mention when not to use it or name alternatives, so the usage context is mainly implied.
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 read-only, idempotent, and non-destructive. The description adds value beyond annotations by revealing the no-args DevTools-snippet behavior and by explaining what each invocation actually analyzes.
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 with numbered check categories and a front-loaded purpose statement. It is a little long, but the length is justified by having three distinct modes with different inputs.
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 zero required parameters and three optional modes, the description thoroughly explains when and how to call the tool. The only real gap is that there is no output schema and the description does not state the expected result format beyond saying content is 'flagged'.
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 covers all parameters well, but the description adds operational meaning: `frames` is for aspect-ratio/crop geometry, `clips` for baked-in pan/zoom, and `edge_frames` for truncated content. This directly helps an agent decide which optional argument to supply.
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 opens with a clear verb and resource: 'Detect cropped content in device-mockup frames' and then enumerates three precise checks (GEOMETRY, MOTION, EDGE). This makes it easy to distinguish from generic page/video audit siblings.
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 gives explicit usage modes: pass `frames` for geometry, `clips` for motion/Ken Burns, `edge_frames` for truncation, and no args to get a DevTools snippet. It does not explicitly state when to prefer an alternative tool for non-device-frame audit 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds return-content transparency by stating it returns structure, when-to-use info, pitfalls, and examples, which is useful 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?
Two sentences, front-loaded with the resource list and followed by return contents and usage triggers. No filler or repeated schema 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?
The tool has 2 optional params fully documented in the schema, no output schema, and annotations covering side effects. The description adds return-value expectations and triggering phrases, making it complete enough for reliable 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 description coverage is 100% — both parameters ('id' and 'search') are already documented in the schema. The description adds no meaningful parameter semantics beyond the framework list, so the 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 uses a specific verb ('Get') and names a distinct resource class ('product-metrics framework') with an explicit list of six frameworks. It is immediately distinguishable from sibling knowledge-retrieval tools by its metric/measurement focus.
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 an explicit trigger condition: use when the user asks 'how should we measure success?' or 'what metrics should we track?'. It does not name when-not-to-use or point to alternatives, but the quoted use cases are clear enough for an agent.
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 adds meaningful behavioral detail beyond the annotations: it states that merged selector validation is applied, and explicitly notes that fixed/flexible roles and allowedTokens are advisory-only labels, not enforced. Annotations already declare readOnlyHint and idempotentHint, so this extra caveat is valuable.
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 action and subject, then a compact caveat about advisory metadata. No filler or repetition of schema/annotation details.
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 single-parameter tool with no output schema, the description adequately explains what is read (template slots), where it is read from (active grab session's DESIGN.md), and the key behavioral nuance (selector validation merge and advisory-only roles). Nothing critical is missing for correct 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?
The input schema already provides complete coverage for the only parameter 'page' with a clear description. The tool description does not add parameter-specific detail, but it does contextualize that the page is evaluated within the active grab session's DESIGN.md. Baseline 3 is appropriate because the schema carries the semantic load.
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 ('Read') and identifies a specific resource: page-scoped template slots from the active grab session's DESIGN.md. The mention of merging overlay selector validation further narrows behavior, distinguishing it from siblings like read_design_md or list_templates.
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 establishes a clear usage context: read page-scoped template slots tied to the active grab session. It does not explicitly list alternatives or exclusions, but the context is clear enough that an agent can infer when this tool applies.
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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint). The description adds useful behavioral context beyond those annotations by explaining the return payload: protocols, guidance, evidence, and a checklist. It does not discuss edge cases like empty search results or content availability for obscure methods, but for a read-only lookup tool this is not a significant gap.
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 dense but well-organized: the first sentence establishes purpose and enumerates the full category map, the second defines the return structure, and the third gives the use case. No sentence is filler or redundant with the schema annotations.
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?
There is no output schema, so the description compensates by specifying exactly what the tool returns ('protocols, do/don't guidance, evidence... checklist'). It also covers parameter categories, use cases, and the safe read-only nature of the call. An agent has enough information to call this tool correctly in the intended contexts.
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 both parameters at 100% with meaningful descriptions, including the category enum and the default value. The description broadly repeats the category families ('qualitative', 'quantitative', 'usability') but adds no parameter-level depth beyond the schema. Baseline 3 is appropriate because the schema carries most of the parameter-semantic weight.
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 with a specific resource: 'Get research method details — qualitative... quantitative... or usability...' It also enumerates what is returned ('protocols, do/don't guidance, evidence, and a checklist'), which clearly distinguishes it from sibling knowledge-retrieval tools like get_principles or get_checklist. The explicit category breakdown leaves no ambiguity about the tool's scope.
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 closes with a clear when-to-use instruction: 'Use when the user is designing a study or asking how to measure something.' It provides a solid usage context without explicitly naming alternative tools or exclusions, so it earns a 4 rather than a 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?
Goes well beyond the annotations by disclosing determinism, the depth-dependent output shape (5 core questions + more_questions vs a flat full list), per-question flags, the voice question's three registers, and an error condition ('throws naming get_taste_interview kickoff otherwise'). Despite that, the phrase 'throws naming get_taste_interview kickoff otherwise' is garbled and slightly obscures the exact error behavior; otherwise this is notably transparent.
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 a single massive block of text with deep parentheticals and run-on sentences, including a garbled clause ('throws naming get_taste_interview kickoff otherwise') that hinders skimming. While front-loaded with the 'START HERE' instruction, the lack of line breaks or focused headings makes even a slightly complex tool much harder to parse than it needs to be.
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 having no output schema, the description covers the core return shapes (questions, more_questions, flat question list), the question structure (skippable, priority, required only for identity), the integration point with audit_taste, and the post-interview persistence step. Some edge cases like presentation of more_questions and exact error handling are only hinted at, but nothing is fundamentally 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 description coverage is 100%, so the baseline is 3; the description meaningfully adds semantics by clarifying why the project parameter matters ('Include it so the interview can show any existing binding'), explaining mode:'refine' behavior (involves keep/tighten/replace), and detailing depth effect on the returned question shape. Not all parameters get equivalent depth, but the added value pushes it above 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 opening sentence says exactly what the tool does with a specific verb and resource: 'returns a deterministic calibration interview.' It immediately establishes the new-project scope ('START HERE on a NEW project') and the refine-already-calibrated alternative, differentiating itself from the sibling tools it pairs with (bind_taste_surface for persistence, audit_taste for later audits).
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 is explicit about when to use it: 'Run this BEFORE the first audit_taste on any project that has no binding yet', 'START HERE on a NEW project', and use mode:'refine' instead of starting over when an already-calibrated user dislikes output. It also prescribes the follow-up action (persist with bind_taste_surface), leaving no ambiguity about the workflow.
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 readOnly, idempotent, and non-destructive behavior, so the bar for additional disclosure is lower. The description adds useful context beyond annotations by specifying that profiles are locally stored and that results include counts and timestamps, helping the agent understand the output shape.
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 with no filler. It front-loads the action and resource ('List locally stored taste profiles') and then adds the key output details in a compact and efficient way.
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 list operation with no output schema, the description sufficiently shares what the agent will receive: rule/corpus counts and last-updated timestamps. It also adds 'stores on the local device' context, which is helpful for distinguishing behavior and nothing necessary 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?
The tool has zero parameters, so the description does not need to explain parameter meaning. Schema coverage is 100% by default because the properties object is empty. A baseline of 4 is appropriate here.
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 and resource: 'List locally stored taste profiles,' clearly identifying the action and target. It also specifies meaningful output traits (rule/corpus counts, last-updated timestamps) that distinguish this from related tools like get_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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied by the verb 'List' and the account of the resource, but the description does not explicitly state when to use it instead of get_taste_profile or create_taste_profile. It conveys obvious usage context without formalizing exclusions or 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, idempotentHint=true, and destructiveHint=false. The description adds value beyond these by disclosing exactly what is produced: frontmatter, Markdown body, and a flattened token index. This is useful and consistent with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
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 action and then lists precisely what the caller receives. There is no filler, repetition, or unnecessary abstraction.
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, single-parameter tool, the description is complete: it identifies the target file, the operation, and the output shape. Annotations cover safety and idempotency, and no output schema is present to require extra return-value documentation.
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 fully documents the only parameter, path, as 'Path to DESIGN.md', so the description does not need to add parameter details. The baseline of 3 applies because schema coverage is 100% and the description does not contradict or add meaningful parameter-level 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 names a specific verb (Parse), a specific resource (DESIGN.md), and explicitly enumerates the returned payload (frontmatter, Markdown body, flattened token index). It clearly distinguishes this read operation from sibling creation/modification tools like init_design_md and 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use context: when you need the parsed contents of a DESIGN.md file. It does not explicitly name alternatives or exclusion conditions, but no competing sibling does exactly the same read-and-parse job, so the context is sufficient.
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 aliases already declare readOnly, idempotent, and non-destructive; the description adds meaningful context with 'Pure offline math.' It also discloses exactly what is computed and returned: smallest foreground adjustment, an alternative background adjustment, and the achieved ratio and direction.
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 avoids verbose fluff. There is some redundancy between 'Given failing WCAG color pairs' and 'audit_contrast's failing pairs,' but each sentence still contributes useful operational context.
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 no output schema, the description is sufficiently explicit about what the tool returns: the minimal color change, the achieved ratio, and direction. It also clarifies it's offline, which helps set expectations. An exact response shape is not described, but enough information exists to call 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?
The input schema covers all properties at 100%, including the 'level' scale and targetRatio override semantics, so the description doesn't need to re-document them. It adds the helpful note that pairs should come from audit_contrast's failing-pair output, but that is more usage context than parameter-level 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 specifies a concrete verb and resource: it computes the MINIMAL color change for failing WCAG color pairs. It also distinguishes itself from audit_contrast by stating that it consumes that audit's failing pairs rather than performing the audit.
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 to feed it audit_contrast's failing pairs to get concrete passing values, which is clear when-to-use guidance. It frames the tool as the fast path instead of brute-forcing colors, though it does not spell out explicit exclusion 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?
The annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context on top: it auto-detects the surface, fans out to the appropriate audit set, and accepts a project for taste binding. It does not discuss every possible caveat, but it does not hide any significant side effect either.
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 compact and front-loaded: it begins with the purpose, then explains the detection/fan-out behavior, then gives the actionable warning to prefer this over granular audit tools. There is no filler or redundant restatement of the schema.
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 wide-dispatch tool with no required parameters, the description is strong because it defines the accepted target types and the relevant check families. However, it doesn't explicitly state that at least one target input should be provided, which matters since all 10 parameters are optional. The wealth of the schema mostly compensates.
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 parameters are already self-documenting. The description contributes general context like 'target' and 'project' taste binding, but most of that meaning is already expressed in the schema. It adds little about parameter formats, precedence, or combinations beyond what the schema communicates.
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 a specific action — 'Run all applicable Raven audits for a target' — and explains the scope with a concrete verb and resource. It also distinguishes the tool from its siblings by explicitly telling agents not to pick individual audit_* tools. This makes the tool's role as an umbrella dispatcher unmistakable.
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 gives direct usage guidance: use this instead of choosing individual audit_* tools. It also explains how the surface is detected and which check families run per surface, so an agent knows this is the right entry point for broad audits rather than for a single focused check.
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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description reinforces this by saying it 'Reads' inputs rather than mutating anything. It adds meaningful behavioral scope: what is inspected (Info.plist, app.json, PRIVACY.md, entitlements, source), and what kinds of issues are flagged. It also notes 'Same return shape as audit_page,' which gives return-consistency context. 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 dense yet well-structured: it leads with the purpose, then input alternatives, optional inputs, flag categories, and finally return-shape consistency. Despite its length, every phrase contributes to the agent's ability to select and invoke the tool correctly. There is no filler or restatement of the name.
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 formats, optional cross-references, many detection categories) and the absence of an output schema, the description provides strong contextual coverage. It states what the tool reads, what it flags, and that it matches the return shape of audit_page. It leaves the exact return structure implicit by referencing audit_page, which is acceptable but not a full output 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?
The input schema already describes and covers all five parameters, so baseline is 3. The description adds key semantics above the schema: it clarifies that managed Expo apps have no Info.plist, that source enables code-vs-declaration contradiction checks, and that transient fields like expo.ios.infoPlist, expo.android.permissions, plugins, and extra are audited. This adds meaningful guidance for how the parameters are used together, supporting a 4.
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 opens with a specific verb and resource: 'Audit an iOS or React Native/Expo app's privacy posture for App Review and user trust.' It precisely names the audit domain and differentiates itself from general-purpose audit siblings like audit_page, audit_ios_a11y, and audit_asset_integrity by focusing on privacy posture.
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 establishes clear when-to-use context: for an iOS/React Native/Expo app's privacy posture in App Review and user trust contexts. It explains that a native Info.plist OR an Expo app.json is read, plus optional supplementary files. It does not explicitly name alternative tools or give exclusion conditions (e.g., 'use audit_ios_a11y if auditing accessibility instead'), but the use case is unambiguous.
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 cover read-only, non-destructive, and idempotent behavior. The description adds meaningful context beyond that: the two-phase interaction, the snippet-based capture flow, the printed JSON shape, and the score categories. It stops short of defining the score output structure, but the core behavior is well disclosed.
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 carry the full workflow with no filler. The purpose comes first, then the two-step invocation, then the sibling relationship. 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?
For a tool with no output schema, the description handles the main gaps well: it names the outputs of both calls and clarifies when to use it relative to audit_page. Some specificity about score shape is absent, but an agent can select and invoke the tool correctly with the information given.
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 already documents the top-level parameters thoroughly (100% coverage), so the description is not required to repeat field semantics. However, it does add useful workflow meaning by tying 'that JSON' to the DevTools snippet output and making it clear the same object should be passed back. This is enough to maintain the baseline 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 names a specific verb and resource: 'Evaluate visual rhythm from a rendered page's geometry.' It also distinguishes itself from audit_page by being 'the complement to audit_page for things only visible once rendered,' which prevents confusion among many audit_* siblings.
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 gives an explicit call protocol: call with no arguments to get the DevTools snippet, then call again with the JSON that snippet emits. It also names audit_page as the alternative and scopes this tool to rendered geometry, so the agent knows exactly when this tool is 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it produces per-relation match/mismatch/uncertain verdicts and gives a concrete layout-drift example. No contradiction with annotations 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?
Two sentences with no filler: the first front-loads the core compare-and-flag behavior and the second concisely tells the caller what inputs to provide. The parenthetical enumerations are dense but necessary for disambiguation.
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 is complete for a read-only comparison tool given its complex nested schema and absence of an output schema: it defines both inputs and the categories of output verdicts. A minor gap is that the relationship checklist's a/b element references and tolerance semantics are left implicit, but the overall context is adequate for correct invocation.
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 0% schema description coverage, the description compensates by naming all top-level parameters (ios, android, checklist) and their broad shapes, and by enumerating the checklist relation domain (vertical centering, baseline/left alignment, equal gap/size, presence, truncation). It does not fully explain what a/b represent or how tolerance is used, but the schema structure plus this context is enough for a competent agent.
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') alongside a clear resource ('iOS vs Android element snapshots') and explicitly names the expected output ('flag per-relation match/mismatch/uncertain'). The cross-platform scope distinguishes it from sibling audit tools such as audit_ios_screen or audit_page without ambiguity.
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 clearly states what should be provided ('Provide ios+android {elements,viewport} snapshots and a checklist[]') and includes an example that signals when the tool is appropriate (cross-platform layout drift detection). It does not explicitly name sibling alternatives to avoid, but the use case is well implied.
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 the tool safe and read-only, so the bar is lower. The description counts credits by adding real behavior: no-arg self-documentation mode, platform-specific thresholds, and nuanced handling of Material/Android semantic colors as warnings rather than failures. It also links its return shape to audit_page.
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?
Five short front-loaded sentences, no filler and no repetition of schema constituents. Purpose, invocation, platform semantics, scored dimensions, and return-shape reference are each given exactly one sentence.
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 7-param tool with nested objects, no required params, and no output schema, the description is strong: it explains the input model via the no-args response and the return contract via audit_page. The only residual gap is scroll_settle and broader return-value detail, but those are partially covered by the self-documented protocol.
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 86%, so the baseline is 3 with no extra param info. The description still adds value: it explains what the platform choice actually changes, and the no-arguments invocation mode is a behavior absent from the schema. It does not clarify the otherwise undocumented scroll_settle, which keeps it below a 5.
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 and resource: 'Audit a rendered mobile screen (iOS or Android) from a view-hierarchy/accessibility snapshot.' It also enumerates what is checked — touch targets, contrast, and visual rhythm — so it is not confused with a single-purpose audit tool and identifies the operation precisely.
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 gives direct invocation guidance: call with no arguments to receive the snapshot shape and capture instructions, pass platform:'android' to change scoring semantics, and omit platform for iOS. It does not explicitly state when NOT to use this tool in favor of alternatives like the specialized audit_tap_targets or audit_contrast, 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, idempotentHint=true, and destructiveHint=false, lowering the bar. The description adds genuinely valuable behavioral context beyond annotations: it uses headless Chromium, samples currentTime before and after a play() attempt, and produces a classification. It fully explains the two paths (live render vs. deterministic classification) and contradicts nothing.
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, all dense with distinct information: the mechanism (multiply, currentTime, play attempt + classification set), the value proposition (catches what static audits miss, with domain context), and the parameter usage. Every sentence earns its place; nothing is repeated from the schema.
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 compensates well for the lack of an output schema by naming the classification categories and the observation method. It covers both potential invocation paths. The remaining gap is the exact return format (how classifications and reasons are represented) — but with a well-endowed schema and read-only annotations, the overall context is complete enough for a capable 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?
Schema coverage is 100%, so the schema already documents all three parameters (url, observeMs, dom_snapshot) with detail. The description goes beyond schema by revealing that url and dom_snapshot are alternative, mutually exclusive entry points — one requires a browser render, the other is a deterministic path without a browser. That relationship is not in the schema and is materially useful to an agent.
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 names a specific verb/resource pair ('render a page... observe whether each <video> actually advances') and precisely delimits the output: each clip classified into playing|paused|stalled|empty|error with a reason. It clearly distinguishes itself from static audit siblings, which it claims to complement by catching black/non-playing videos that static audits miss.
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 clear usage context ('catches black/non-playing videos that static audits miss — the most common real-world defect on marketing sites with video content'), which is an implicit when-to-use signal against static audit alternatives. It also explains the two calling modes within the tool: url-based rendering and snappable deterministic dom_snapshot input. It does not name a specific alternative tool and does not state when NOT to use it, so it is not a 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 signal read-only, idempotent, non-destructive behavior, so the description is not required to duplicate that. It adds useful behavioral detail by specifying that the output is a self-contained HTML page, that two-actor rendering creates a line of interaction between the swim lanes, and that ideal-state mode changes the output to side-by-side. 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 compact and front-loaded: the first sentence states the core behavior, and the rest only explains mode selection and optional behavior. Examples like 'customer ↔ lawyer' are immediately clarifying rather than synthetic fat, and nothing is repeated unnecessarily.
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 rendering tool with nested parameters and no output schema, the description sufficiently communicates what is generated, when actors are needed, and how the optional ideal state changes the result. It could also describe more edge behavior, but the mode explanations and schema documentation jointly make the tool practically usable.
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 covers all parameters with descriptions, so the baseline is at 3. The description adds value by interpreting `actors` as the runtime switch between two fundamentally different rendering modes and by clarifying that `ideal` triggers a side-by-side comparison. This semantic guidance goes beyond a field-by-field schema listing.
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 names the deliverable explicitly — a self-contained HTML service blueprint — and the main verb is specific: 'Render'. It also distinguishes two supported modes (single-actor Shostack and two-actor HI-loop), so an agent can quickly tell what this tool does and how its forms differ.
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 gives a clear condition for choosing a mode: omit `actors` for classic single-actor rendering, provide `actors` for the two-swim-lane layout, and optionally provide an ideal-state for side-by-side rendering. It does not explicitly compare against sibling tools or give 'when-not-to-use' guidance, but the mode selection rules are concrete and decision-ready.
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 annotations already declare read-only and non-destructive behavior, and the description adds important context beyond that: permission values in the snapshot are advisory display labels only and are not enforced. This is a meaningful behavioral disclaimer that prevents misuse.
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 front-loaded sentences, no filler. The first states the action and resource; the second adds the permission caveat that an agent genuinely needs. 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?
For a one-optional-parameter, read-only, idempotent tool, the description gives the essential return concept ('layer-tree snapshot') and the caveat about authoritative semantics. A minor gap is not describing failure behavior when no active local grab session exists.
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 the single optional page parameter is already fully documented in the schema. The tool description does not need to add param semantics but does not go beyond the schema either.
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 ('Read') and defines a clear resource: the latest non-mutating layer-tree snapshot from the active local grab session. This clearly differentiates it from siblings like get_grabbed_elements and move_grab_layer.
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 provides clear when-to-use context: when the agent needs the most recent layer-tree snapshot from the active local grab session. It does not explicitly name alternatives or state when not to use it, so it stops short of full exclusion guidance.
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=true and destructiveHint=false, but the description adds substantial detail beyond them: the returned artifact applies on top of the diff's post-image, applying is a separate caller responsibility, and judgment-heavy findings are deferred to manual. It also discloses determinism and internal re-verification behavior. No annotation 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?
Three sentences, with the core purpose front-loaded in sentence one, followed by output semantics and verification behavior. Each sentence earns its place, though the second is dense and the third contains a minor grammatical issue ('a judgment-heavy findings'), keeping it from a 5.
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?
There is no output schema, so the description correctly carries the return contract: the tool yields a unified patch with explicit post-image semantics and a caller-side apply step. It covers the verification-behavior and the scope of the tool well enough for an agent to invoke it safely.
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 diff, project, and design_md already carry detailed structured descriptions. The tool description itself adds no extra parameter-level nuance beyond what the schema states. Baseline 3 applies because the schema 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 uses specific verbs ('Review', 'propose') and a precise resource: added UI-code lines and deterministic DESIGN.md token substitutions. It clearly states what the tool does NOT do ('without writing files'), which implicitly distinguishes it from write-focused siblings like update_design_md. The purpose is unmistakable even without naming 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 gives clear workflow context: the tool produces a unified patch that the caller must apply as a separate step, and it re-verifies the proposed lines. However, it never explicitly names an alternative (e.g., review_diff) or states when-not-to-use, so the exclusion guidance is implicit rather than spelled out.
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 goes well beyond the readOnlyHint and idempotentHint annotations by disclosing that the tool is pure offline with no browser or network, that it infers the canonical modal value when no token is supplied, and that it flags silent cross-page disagreements. This gives meaningful context about how the audit behaves, not just what it returns.
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 compact and well-organized: purpose, input contract, behavioral notes, blind-spot warning, then return summary. Every sentence contributes unique value, and the most important facts are front-loaded.
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 having no output schema, the description clearly enumerates what the tool returns: per-page extraction, consistency dimensions, outliers, issues, score, and summary. It gives an agent enough context to confidently invoke the tool and interpret the result without further lookups.
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 already describes all parameters, including the semantic difference between supplied tokens and corpus-modal inference. The description adds useful guidance about collecting pages from different routes and not needing the design token in advance, but it doesn't significantly expand on the individual parameter formats 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 states a specific verb and resource: audit multiple pages for cross-page consistency of container width and hero heading tier. It clearly differentiates itself from audit_page by naming the issue #9 single-blob blind spot where pages each pass individually but disagree with each other.
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 the agent to pass ≥2 pages collected from different routes on the same site, making the primary use case explicit. It references audit_page as the related single-page tool, but it does not fully spell out all when-not conditions or explicitly compare against the wider set of audit 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?
Annotations already declare readOnly/idempotent/non-destructive, and the description goes far beyond these by revealing a genuine non-obvious behavior: url mode OMITS per-element rows for passing elements and explains why (typical page generates hundreds of thousands of characters of them). It also describes the two-mode return shape difference, determinism between input modes, and overload since with manual computing — exactly the behavioral detail an agent needs to set output expectations.
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?
Every clause in the description earns its place — scope, thresholds, failure semantics, mode differentiation, and the rationale for omission are all loaded with concrete facts. The text is dense and readable, though it is a run-on multi-clause paragraph with dashes and commas that could be crisper as separate structured sentences, which costs it a point toward full 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?
With no output schema present, the description still communicates per-mode return shapes, the specific failure row categories (aa_failures, indeterminate_bg_rows), and the omission behavior that affects downstream processing — a near-complete picture for an analysis tool. Minor leftover ambiguities are the aggregation details of 'counts' and how AAA failures are explicitly represented in url mode, so slightly more mandated detail would reach 5.
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 baseline is 3 and the schema already documents each parameter. The description adds real semantic value above that by encoding what each option produces, e.g. url mode yields aggregated counts plus only action rows whereas dom_snapshot yields a per-element mapping, and it distinguishes the analytical purpose of the inputs. It stops short of describing format details per parameter, so 4 rather than 5.
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 a precise verb and resource: 'Compute WCAG contrast ratios for every text element' from a URL or a dom_snapshot, and spells out the concrete output (AA 4.5:1/3:1 and AAA pass/fail, failing pairs with selector, ratio, delta-to-pass). This makes it immediately differentiable from look-alike siblings like audit_contract or suggest_contrast_fix without needing to open any schema.
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 clearly defines the two invocation routes and what each returns — 'dom_snapshot mode returns a row per supplied element; url mode returns counts plus every row that needs action — so an agent knows which input to use in which situation. It also implies the intended use case ('replacing manual eyedropper + ratio math'), but it does not explicitly state exclusion cases or point to an alternative sibling for other needs, such as suggest_contrast_fix for remedies.
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?
With readOnlyHint, idempotentHint, and destructiveHint=false annotations already covering the safety profile, the description adds meaningful behavioral detail: it performs a real browser render, requires headless chromium, categorizes flags into 'likely-oversight' versus 'intentional', and returns a table with specified columns. This gives the agent a clear mental model of what will happen and what comes back.
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 fluff: first sentence states the action and detection mechanism, second explains the categorization, third states the output shape and a hard requirement. It front-loads the core purpose while 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?
Despite having no output schema, the description discloses the output table columns, the distinction the tool draws, the technical prerequisite, and the operation. Combined with the annotations and fully described parameters, an agent has enough context to select and invoke the tool 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 parameters URL, breakpoints, and viewportHeight are already fully documented in the schema. The description only adds that URLs are rendered at multiple breakpoints, which does not materially extend parameter understanding 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 states a specific action ('flag content elements that are visible on desktop but hidden on mobile') against a specific resource (a rendered URL) and enumerates the exact CSS conditions it checks. It also distinguishes this audit from general audit siblings by naming the hidden-on-mobile content bug it targets.
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 makes the intended use case explicit: auditing a URL across breakpoints for content that disappears on mobile, with a clear environment prerequisite (headless chromium). It does not explicitly name sibling alternatives or say when not to use the tool, but the use case is specific enough that an agent can recognize when it applies.
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?
Beyond the already-declared read-only and idempotent annotations, the description discloses exactly what the audit flags and rewards, including dark-mode handling being conditional on multi-mode apps. This gives an agent a reliable model of the tool's 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 dense but efficient: purpose first, then check list, then boundaries, then return expectation. Every sentence earns its place, and the longest sentence is a useful enumeration rather than filler.
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?
With rich parameter schema, annotations covering safety, and no output schema, the description still ties the return behavior to an existing shape: 'Same return shape as audit_page.' It also gives enough audit-criterion detail and boundary context for real selection and 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?
The schema description coverage is 100%, so each of the 5 parameters already documents its meaning, defaults, and effects. The main description doesn't repeat or deeply expand individual parameter semantics, so the baseline 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 names a specific verb and resource: 'Audit React Native / Expo source against iOS HIG + Android Material conventions' and immediately lists concrete checks like missing accessibilityLabel, insufficient hitSlop, and allowFontScaling. It also clearly differentiates itself with 'RN-native checks only — no web/CSS or SwiftUI rules.'
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 gives a clear scope boundary ('RN-native checks only') and an explicit way out for rendered screens: 'RN renders to native widgets, so audit_ios_screen scores the rendered screen.' It does not fully spell out alternatives for CSS/SwiftUI or when audit_page would be a preferred choice, but the context is easy for an agent to follow.
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 establish this as read-only, idempotent, and non-destructive. The description adds behavioral context beyond those annotations by disclosing the headless-Chromium dependency for URL mode and listing the exact report shape, including findings with rule, severity, message, and fix. 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?
Each sentence serves a purpose: scope, input modes, report contents, and distinction from a sibling tool. The report breakdown into (a), (b), and (c) is compact and readable without losing necessary specificity.
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 audit tool with no output schema, the description is unusually complete: it names both modes, the external Chromium requirement should not return any malicious URL, and it enumerates the return fields (scale, line_height, weight_ladder, nodes_analyzed, findings). The only minor ambiguity is behavior when neither input is provided, but the 'or' wording sufficiently implies that at least one mode is expected.
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 already documents both parameters fully, which sets a high baseline. The description adds value by framing URL and nodes as alternative modes, telling agents to pass 'a URL or a pre-collected snapshot,' which clarifies how to decide which parameter to populate.
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 opens with a specific verb and resource: 'Audit the typographic SCALE...', then enumerates exactly what it reports (modular scale, line-height consistency, weight ladder). It also explicitly distinguishes itself from audit_page's pass/fail typography checks, so an agent can select it correctly among 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 gives two clear input modes — a rendered page via URL or a pre-collected nodes snapshot — and notes that 'URL mode requires headless chromium.' It also says the tool goes beyond audit_page's pass/fail typography checks, providing useful alternative context, but it does not fully spell out when-not-to-use conditions.
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?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses key behavioral traits: the board never invents swatches, ground scheme is measured, pattern credits are preserved, unusable image paths are skipped with a named warning, and mode:'board' throws when no surface binding exists. It also flags the tool as an APPROVAL STOP and explains the downstream design-system generation it does not invoke.
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 but long and run-on, mixing many clauses in a single paragraph. Every sentence contributes value, but the structure could be broken into shorter, more scannable statements. There is no filler, yet it does not achieve the concise front-loaded clarity of the best definitions.
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 fully compensates by specifying the output files (HTML + best-effort PNG), the output location, the two modes, prerequisites, error behavior, and next steps. It also covers important edge cases such as image-path handling and missing surface bindings, making the description a complete guide for calling the 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 the baseline is 3. The tool description adds a little framing for image_paths and mode:'example', but those are mostly already present in the parameter descriptions. The description does not meaningfully compensate or enrich 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?
The description opens with a specific verb and resource — 'Compose a mood board' — and enumerates precisely what goes into it (design_notes chips, captured references, pattern-library thumbnails) and where it is written (moodboards/ directory or output_dir). It also differentiates this tool from the closely related generate_design_system by explicitly stating this tool never runs it, and it disambiguates the two modes ('board' and 'example').
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?
Provides explicit when-to-use guidance: right after the kickoff interview binds a surface, or with mode:'example' to seed thinking before the interview. It also names alternative/fallback tools — get_taste_interview for missing binding and generate_design_system as the next step — and states when this tool is never to be used (it never runs the system).
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 cover read-only, idempotent, and non-destructive behavior, so the description needed less safety disclosure. It adds useful behavioral context by noting each trend is time-stamped, includes fit/fail assessments, and should not be treated as a prescriptive directive — all beyond what the 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?
Two focused sentences deliver the core purpose up front, followed by concrete trend examples and an important usage caveat. Every sentence earns its place, with no redundant filler or restatement of the tool name.
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 informational tool, the description is complete. It explains what the trend data contains, gives representative examples, clarifies that trends are time-stamped, and tells the agent how to interpret the results — including the calibration caveat.
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 zero parameters and 100% schema coverage, so there is no parameter ambiguity requiring explanation. The description still enriches the input semantics by indicating that the tool is self-contained and returns a curated trend set rather than needing filters or configuration.
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 a specific verb ('Get') and resource ('current brand and visual-design trends') and goes further by listing concrete examples like bento grids, monospace type, and generative patterns. The 'current/2026/time-stamped' framing distinguishes it from static brand reference tools such as get_brand_system or get_brand_principles.
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 clearly communicates the intended use — checking current trend fit and calibration — and adds a strong usage caution: 'treat as a calibration signal, not a prescription.' It does not explicitly name sibling alternatives or exclusions, but the context is specific enough for an agent to select it appropriately.
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 establish that this operation is read-only, idempotent, and non-destructive, so the description only needs to add value beyond safety. It does by describing the return content (do's and don'ts examples, evidence, checklist), which is particularly helpful because there is no output schema. No hidden behaviors, side effects, or constraints are missing.
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 long with no filler and front-loads the key noun phrase. It includes only the essential facts: what patterns are available and what the response contains. Every sentence contributes useful context.
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 one-parameter, read-only tool with no output schema, this description is complete. It gives the agent the full scope of the parameter, describes the result contents, and relies on annotations to communicate the safe, idempotent nature of the call. There is little missing information that would prevent a correct invocation.
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 already fully covers the parameter, so the baseline is 3. The description adds value by framing the type as copy recipes and listing the four domain categories in natural language, helping an agent reason about what value to pass beyond the raw enum labels. It doesn't repeat schema list verbatim, but it does make the parameter's meaning and expected content clearer.
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 ('Get') and a specific resource type ('content pattern'), and details the exact copy recipe categories covered (error messages, empty-state, notifications, form validation). It also clarifies what the returned content includes, separating it from more general tools like get_principles or get_pattern. This is enough for an agent to know what this tool is for.
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 clearly indicates when to use the tool: when the agent needs copy recipes for these specific UI content categories. It gives a strong use context, but it does not explicitly mention alternatives or exclusions relative to sibling tools like get_content_principles, which keeps it just below an explicit 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 declare the tool read-only, idempotent, and non-destructive. The description adds useful context beyond annotations: the exact content scope (14 points), its government origin, and its broader applicability as a service-quality checklist.
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 with no filler: the resource, its contents, and the intended use case are all front-loaded and purposeful. 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?
For a parameterless retrieval tool, the description fully covers what the service standard is, how many points it has, why it matters, and when to invoke the tool. No additional context is needed.
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 zero parameters and 100% schema coverage, so there is nothing for the description to explain. It meets the baseline for parameterless tools.
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 names a specific verb and resource — getting the GOV.UK Service Standard — and specifies exactly what it contains: 14 points for evaluating service readiness. This clearly distinguishes it from generic siblings like get_checklist or get_principles.
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 gives an explicit trigger: 'Use when the user asks how to evaluate a whole service.' It does not enumerate exclusions or alternative tools, but the invocation context is clear and actionable.
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 establish readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral nuance beyond annotations: it states that bindings are per-project and do not transfer, it discloses that the returned data includes a full catalog and corpus, and it explicitly warns against treating it as a calibration step. This adds real 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?
The description is compact: one sentence states the operation and return value; a second sentence delivers the critical caveat and routing instruction. There is no redundant phrasing, no filler, and the most important distinguishing behavior ('NOT a calibration step') is prominent.
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 not having an output schema, the description enumerates the three components returned: rule catalog, precedent corpus, and per-project bindings. It also provides the key behavioral caveat about binding transfer and names the sibling to use instead when the binding is absent. For a single-parameter read-only tool, this is sufficient for an agent to call it correctly in context.
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 only parameter 'name' is described simply as 'Profile name.' The description reinforces that loading is by name but adds no additional semantic detail about format, validation, or expected values. Baseline 3 is appropriate because the schema already carries the semantic load.
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 names a specific verb ('Load'), a specific resource ('locally stored taste profile by name'), and specifies the result contents (rule catalog, precedent corpus, per-project surface bindings). It also distinguishes itself from the calibration flow by explicitly stating what it is NOT, which sets it apart from get_taste_interview and list_taste_profiles.
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?
It provides an explicit alternative in get_taste_interview with a clear condition: when working on a project without a binding, call the interview instead of using this tool. It also warns that bindings are per-surface and do not transfer, which prevents misapplication. The context for when this tool is appropriate is clear from the contrast.
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?
Beyond the readOnlyHint, the description states the exact data source ($RAVEN_USAGE_LOG or ~/.raven/usage.jsonl), confirms no network activity, and explains the report contents, including the interpretation that repeated audit warnings indicate knowledge gaps. This gives the agent a clear mental model of side effects and information boundaries that annotations alone do not fully 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?
The description is compact, front-loaded with the core purpose, and every sentence adds useful information. The trigger phrases and the network clarification are placed logically and no filler 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?
For a lightweight read-only tool with one well-schema'd parameter, the description covers purpose, the exact return content themes, data provenance, local-only behavior, and invocation triggers. There is no output schema, but the listed report categories are enough for an agent to invoke and interpret the result. The safety profile is also confirmed by the readThroughHint and idempotentHint annotations.
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 sole parameter `days` is already fully described in the schema with a default of 30 and a range. The description repeats the 'last N days' idea but does not add constraints or semantics beyond the schema. Since schema coverage is 100%, a 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 names a specific verb ('Summarize how Raven has been used') and a concrete resource (the local usage log), and lists exactly what the report includes: top called tools, repeated audit warnings, looked-up patterns/design systems, and brand-style companies. This clearly distinguishes it from the many sibling audit and design tools, which focus on individual domains rather than reflecting on Raven usage itself.
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 gives explicit trigger phrasings: 'what have I been building with Raven' or 'what's Raven missing'. It also clarifies this is a local-log operation rather than a network fetch. It does not mention competing alternatives or when not to use this tool, but for this unique reflective tool the call framing is unusually explicit.
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 mark it read-only and non-destructive, and the description goes further: it discloses deterministic scoring from the same checks as audit_page, the optional headless-chromium rendering behavior, the overall 0-100 and grade output, and specifically which categories are not mechanically assessed. This gives meaningful 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 detailed but every sentence adds value: what is scored, how the score is derived, the two input modes, returned values, and the coverage limitation. It is front-loaded with the core purpose and avoids filler.
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 no output schema, the description provides the important return values: per-category 0-10 scores, overall 0-100 score, A-D grade, the weakest category, and guidance on unassessed categories. Combined with full parameter schema coverage and annotations, nothing essential is missing for an agent to select and invoke the 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 the schema already documents url, html, strict, and containerMaxWidth. The description reinforces the url vs html distinction and rendered DOM behavior, but it does not add significant new parameter semantics beyond what the schema states. The baseline 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 opens with a specific verb and resource: 'Score an HTML/CSS page across 7 design categories'. It lists the categories and clarifies the scoring scales, so an agent knows exactly what the tool produces and can distinguish it from audit-style siblings like 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 gives clear context for invocation by specifying two routes: pass html directly, or pass url for rendered-DOM scoring. It also references audit_page and the categories not mechanically assessed, which hints at the tool's place relative to alternatives. It does not explicitly state when to prefer score_page over audit_page, but the usage context is clear.
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, idempotentHint, and destructiveHint: false, but the description adds far more: not_assessed instead of guessing, rule delegation to Raven engines, silence-over-speculation policy, accepted contract corpus precedents, design-note verification as acceptance criteria, and build_hints on expensive techniques. The description and annotations align; there is 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is very long and runs as one dense paragraph, so it is not structurally graceful. However, nearly every sentence carries a distinct behavioral policy or edge case that matters, and the opening line immediately gives the core function. The density is mostly earned rather than padded.
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 an 8-parameter tool with no output schema, the description is unusually complete. It covers target variants, scope resolution, project binding prerequisites, document_kind behavior, verdict semantics, finding types, fidelity_findings, note assessments, REF-* deltas, restraint findings, and build_hints. An agent has nearly everything needed to select and invoke 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%, so the baseline is 3, but the description meaningfully supplements the schemas. It explains url's rendered headless scroll-settle behavior, surface omission as warn-not-block, project binding resolution, source_text as a verbatim token diff, and document_text's artifact/portrait distinction for note fidelity. These are behavioral semantics the schema alone cannot convey.
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?
Opens with a specific, non-tautological purpose: 'Judge a target against a taste profile'. It also names the concrete input modes (html, text, url) and the meaningful output dimensions, which separates it from the many generic audit_* siblings. The tool is clearly associated with taste profiles rather than generic page-score or checklist audits.
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?
Gives strong selection and run-order guidance: pass url/html/text depending on target type, pass surface to control scope-tagged rules, pass project to reuse a saved surface binding, and run get_taste_interview first for a new project with no binding. It does not explicitly exclude sibling audits, so an agent still has to infer when not to use this tool in favor of, for example, audit_page or audit_content.
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 annotations already mark it read-only and idempotent, and the description adds substantial behavioral context on top: both pages are rendered headless and measured from live computed CSS, never from recall. It also discloses the reference-guardrail behavior (don't copy the reference's copy, marks, imagery, or brand color), which is exactly the kind of behavioral nuance annotations cannot express.
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 text is long but dense, and every sentence contributes: input, measurement method, dimensions, outputs, the on_par loop, and the standard-vs-source rule. It loses a point only for being a single unwieldy paragraph rather than a more scannable structure.
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?
With no output schema present, the description thoroughly enumerates the full return shape: both raw measurements, per-dimension diffs, concrete derived bars, a human-vs-mechanical fix list, and the on_par boolean. Combined with the loop usage, this is remarkably complete for a tool with nested parameters and nuanced measurement behavior.
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 already covers all parameters, so the baseline is high. The description adds semantic weight by clarifying that subject_url is the page being improved, reference_url is the benchmark whose values derive the bar, and that both are measured the same live way. This qualifies the meaning of the parameters beyond their 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 names the exact question it answers, defines the tool as a live, headless comparison of a subject page against a reference page, and enumerates the nine measured dimensions. This clearly differentiates it from sibling audit or scoring tools because the core is comparative benchmarking with a verdict boolean.
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 places the tool inside a loop: build, critique against renders, re-run, and only consider work done when verdict.on_par is true. It also gives a clear rule for interpreting the reference page — a standard, not a source — though it doesn't name alternate sibling tools or give explicit when-not-to-use cases.
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 goes far beyond annotations, disclosing deterministic behavior, matcher semantics, family-binding constraints, gap handling, diagnostics, coverage, and the fact that it never invents tokens or writes code. It aligns with the readOnly and idempotent hints, with 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?
The description is long but every sentence contributes critical algorithm or outcome information. It is front-loaded with the core map-and-generate purpose, then packs in precise matching rules and edge cases without any 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?
The description covers major behavioral aspects: matching rules, gaps, diagnostics, no-token projects, and the guarantee that it does not invent values. However, it does not specify the concrete return shape (e.g., property-to-token/gap record), which would be valuable since no output schema exists.
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 value beyond the schema by explaining how thresholds are used (RGBA 0 exactly, near under 12, length under 2px, unitless within 1%, root 16) and the token-family restriction. It does not map to every parameter individually, but the overall semantics enrich 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 states the exact verb 'translate', the resource ('a captured pattern's raw literals'), and the target outcome ('onto the project's own design tokens'), with concrete examples. It clearly distinguishes this tool from the many reference-capture and design-system reading siblings.
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 gives clear context for when to use the tool: when you have a captured pattern's raw values and want generated code to use the project's own tokens. However, it does not explicitly name alternatives or say 'do not use this when ...', leaving room for an agent to infer the boundaries.
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 establish read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context by stating that no scan is performed and by listing what each rule entry contains, going beyond the annotation baseline.
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. The core purpose is stated up front, and the usage guidance is delivered in a clear second sentence.
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 zero-parameter, read-only enumeration tool, the description covers purpose, usage boundary, and the shape of returned data. It does not formally define 'taste scope' or an example response, but this is a minor gap given the simplicity of 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?
The tool has zero parameters and the schema indicates no properties, so there is nothing for the description to explain. A 0-parameter tool is already fully covered by the schema and annotation 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 explicitly states the verb 'Enumerate' and identifies the exact resource: Raven's Talon detector rule corpus. It also names the fields returned, which makes the tool's scope concrete and differentiates it from the sibling talon_scan.
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 gives an explicit use case: show a client why before or instead of running talon_scan. It also clarifies that no scan is required, which prevents the agent from confusing this tool with the actual scanning sibling.
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?
Beyond the readOnly/idempotent/destructive annotations, the description reveals what the audit will score (44×44pt targets, contrast, visual rhythm), that iOS semantic colors like secondaryLabel/tertiaryLabel are treated as platform-standard with warn-not-fail behavior, and that screenshot is optional. This materially clarifies 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 compact, front-loaded with the core purpose, and every sentence carries distinct value: purpose, alias relationship, no-args usage, example payload structure, scoring criteria, and return shape reference. No redundant filler.
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 analysis tool with rich schema coverage and annotations, the description fully covers what inputs are needed, how to invoke it, what scoring dimensions are inspected, and what return shape to expect. The no-arguments behavior and alias note make it safe for an agent to use without additional research.
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 baseline is 3. The description adds meaningful usage semantics by showing an expected elements payload and viewport shape, and clarifying that the screenshot is optional. It also gives key scoring semantics such as point-based dimensions and warn-not-fail color handling.
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 a rendered iOS screen from a view-hierarchy/accessibility snapshot, and explicitly identifies it as an alias of audit_screen with platform 'ios'. This distinguishes it from broad siblings like audit_page and audit_screen while also signaling the return shape.
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 gives clear usage context: call with no arguments to see the expected snapshot shape, or call with elements and viewport to perform scoring. It also names the alias relationship and the same return shape as audit_page. It does not explicitly call out alternatives or exclusions, but the iOS scope provides adequate guidance.
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 annotations already establish that this is safe, read-only, open-world, and idempotent, and the description adds meaningful behavioral detail beyond that: it uses headless Chromium and real getBoundingClientRect when a url is provided, is fully non-rendering in elements mode, requires headless Chromium for url mode, and returns a sorted worst-first fix table. It describes the output table fields in enough detail without an output schema.
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 dense but efficient: it lists the affected element selectors, the output columns, the CRUCIAL behavior difference between the two modes, and the default threshold. There is no filler or repetition from the schema. Every sentence contributes a distinct piece of information an agent needs.
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 no output schema and only annotations, this description covers everything: what gets audited, what the audit emits, what measurements mean, the minimum-size default, the two accepted input modes, and the environmental requirement (headless chromium for url). It is fully actionable for an agent deciding whether to call the tool and how to invoke it.
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 baseline is already 3. The description adds extra value by explaining that url triggers rendering and measurement, while elements is a pure no-browser mode, and by explicitly stating the 44px default that minSize controls. This goes beyond what the schema says without being overly verbose.
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 names the specific audit standard (WCAG 2.5.5 / Apple 44pt), the exact resource being audited (web interactive elements), and the concrete output (per-element fix table). It clearly differentiates this from the many sibling audit tools because it is specifically about tap-target dimensions and proposes CSS fixes.
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 gives clear guidance on when to use each input mode: pass a url for real headless-chromium rendering plus measurement, or pass pre-collected elements[] for a pure, no-browser snapshot audit. It does not explicitly state when to choose this over sibling alternatives like audit_ios_a11y or audit_page, so it stops just short of full routing guidance.
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 thoroughly discloses side effects: it stores a JSON record under ~/.raven/references, truncates html over 8000 chars, rejects style maps over 200 properties, rejects non-http(s) URLs, gives every record a fresh ref_id, and attempts an offline PNG thumbnail with best-effort fallback. The annotations only say destructiveHint=true; the description carries the full behavioral burden and does it well.
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 dense but each sentence adds useful context: invocation order, storage behavior, truncation/rejection rules, thumbnails, and exclusions. It is slightly long, but the length is justified by the number of behavioral caveats an agent needs to know before calling a capture-and-persist tool.
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 12-parameter mutation tool with no output schema, the description covers the essential ground: what gets persisted, where, what constraints apply, what happens if the browser is unavailable, and which related tools handle adjacent concerns. It doesn't state the response shape beyond mentioning ref_id, but an agent can call the tool correctly without that detail.
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 baseline is 3. The description adds value by telling the caller to pass fields exactly as returned from get_grabbed_elements and by highlighting runtime constraints on html length, style property count, and URL scheme. It doesn't add much on parameters like owner or tags, but the schema already explains those clearly.
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 opens with a clear verb and resource: 'Persist a pattern grabbed from any page so it survives the browser tab.' It also explicitly distinguishes itself from map_reference_to_tokens by stating what it does not do, so an agent can tell which tool to use without opening the schema.
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 gives an explicit call sequence: call it after get_grabbed_elements returns a selection, and pass that selection's selector/styles/html/rect/stateStyles plus the URL. It also gives a negative case: mapping onto project tokens belongs to map_reference_to_tokens, and this tool does not fetch the source URL.
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 discloses important side effects beyond the raw annotations: recorded decisions evolve future get_taste_interview kickoffs, recurring choices become suggested defaults, and uncovered categories become new interview questions. This makes the persistent side effect of each record explicit and is not contradicted by 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 long, but every sentence advances agent understanding: when to call, what to record, what the fields mean, and what happens afterward. It is front-loaded with the core recording action and the 'moment it is made' rule before moving to supporting details.
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 7 parameters, 4 required, and no output schema, the description covers the purpose, the triggers, the source values, the content requirements, and the downstream consequences. The missing response format is not a blocker because the tool's main value is the recorded side effect described clearly.
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 schema describes all parameters at 100% coverage, the description adds meaningful semantics with concrete examples and the causal consequences of dimension categories. It also explains what makes a record useful—user-overriding generated choices is a high-signal record—which goes beyond the schema's field names.
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—record—and clearly identifies the resource as the Taste Engine's learning loop for taste, direction, and design decisions. It distinguishes itself from generic decision or review tools by centering on taste-related decisions captured during real work, not just interview time.
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 gives clear timing guidance: record the moment a decision is made during real work, and record liberally because every committed decision is calibration data. It does not explicitly name a sibling alternative or call out when not to use the tool, so it stops short of a full 5.
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 goes well beyond the annotations by disclosing deterministic ordering, return shape, skipped[] for corrupt records, that it never fetches the source site, that markup is omitted by default, and that results carry display/credit info. These are important behavioral traits not visible anywhere in the structured metadata.
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 key use call and gives strong behavioral guidance, but it is long and contains some redundancy — for example, the return payload details are stated across overlapping sentences ('Every result carries a score and a why' / 'Every result carries a display object'). Still, nearly all content 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?
With no output schema, the description must carry the return-value explanation, and it does so thoroughly: score, why, display object, image_path, html_available, html_truncated, skipped[] for corrupt records, and the no-fetch/no-ranking guarantee. An agent has enough context to call the tool and interpret results correctly in most situations.
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 real semantics on top: filters compose with AND, the free-text query expands through Raven's controlled vocabulary, include_html is off by default because of authorship concerns, and corrupt records go to skipped[]. This goes well beyond the schema's individual 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 opens with a specific verb and resource: 'Find patterns previously kept with capture_reference,' and gives concrete use cases like recalling 'that hero from Linear.' It clearly distinguishes its scope from capture_reference and other knowledge tools by tying results to previously captured references.
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 gives explicit context for when to call the tool: before rebuilding something already captured, or when recalling a specific known pattern. It also explains when to use include_html versus the default behavior. However, it does not explicitly name sibling alternatives such as search_knowledge and say when to choose those instead, so it stops short of full exclusionary guidance.
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 readOnly/openWorld/idempotent, so the bar is lowered, and this description still adds substantial context: findings are never dropped, taste-binding overrides return findings flagged as waived_by_taste:true, geometry rules require premeasured elements+viewport, and every finding is traceable to a principles source.
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 information-dense, front-loaded, well worth its length, and reads naturally. It earns a 4 rather than 5 because the dense enumeration of rule categories and nested parentheticals makes the paragraph quite long and less skimmable than a more structured summary.
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?
Even with no output schema, the description effectively conveys what a caller should expect: findings with citations, possible waived flags, and no dropping. It also covers the interaction between all meaningful parameters and the conditions under which features activate, making it complete enough to select and invoke safely.
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, but the description goes far beyond the schema by explaining which input mode activates which rules, how project/profile/waivers affect results, and that surface scoping is optional. This is the kind of semantic gloss that makes the tool safe and effective.
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?
States a specific verb+resource: runs Raven's deterministic detector engine over a page, and clearly distinguishes itself from LLM-based evaluation by saying 'no LLM, pure measurement.' It lists the concrete rule domains, so an agent knows exactly what class of checks this tool performs.
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 clear context: pure/deterministic measurement, three input modalities, conditions for geometry rules, project profile resolution, and surface scoping. What keeps it from a 5 is the absence of explicit alternative-routing ('use audit_page for X instead' or a named sibling comparison).
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?
Beyond the annotations' destructiveHint, the description adds substantive behavioral context: irreversibility, no trash, exact host-with-subdomains matching, domain matching edge cases, local-only scope, and 'contacts nobody'. It also discloses response behaviors like appeared_since_preview, skipped, and failed results. No contradiction with annotations is present.
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 long, but every clause carries contractual detail: target mode, irreversibility, host-matching semantics, expected_ref_ids behavior, return channels, and edge cases. It is front-loaded with the essential action and structured to communicate complex destructive behavior without flat phrases.
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?
With no output schema, the description compensates thoroughly by specifying every relevant return channel (ref_ids, appeared refused, skipped, failed) and the failure semantics (unparseable JSON, non-deletable records). It also covers all four parameters and the main destructive edge cases, so an empty element can execute it correctly and understand partial results.
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 full, and the description adds material meaning: exact-plus-subdomain matching, IP self-only matching, the reason confirm is required, and how expected_ref_ids pins the removal. This goes beyond the verbal Chinese 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 opens with a clear verb-resource pair, 'Remove stored patterns from the local corpus', and explicitly distinguishes the two target modes: by ref_id or by host. It also names itself 'the takedown path', differentiating it clearly from capture/reference-search siblings.
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 exactly when to use the tool (site takedown, removing a single known ref, host-wide removal) and when host-wide removal requires confirm:true. It does not explicitly name an alternative non-destructive sibling, but the usage context and safety constraints are otherwise explicit and unambiguous.
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 mark it read-only, idempotent, and non-destructive. The description goes much further by disclosing the exact return shape (per-item pass/warn/fail verdicts, matched principle ids, concrete issues, before→after rewrite, aggregate summary), the deterministic heuristic rules per content type, and the offline execution model. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence carries information: purpose, return format, heuristics, offline behavior, and a sibling-pointer. The content is packed but not repetitive, and it is front-loaded with the core purpose before the details. Nothing is extraneous.
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?
The tool has 3 parameters, no output schema, and a large sibling set, but a call agent can invoke it correctly. The description covers the input domain, the heuristics, the return value, the offline behavior, and the alternative tool condition. Any missing details, such as array size limits, are nonessential for a read-only deterministic audit 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 description coverage is 100%, so the baseline is 3. The description adds meaningful semantics on top by tying each `items.type` enum value to the heuristic that applies (e.g. metric must carry a number+unit, CTA/label action-led and ≤4 words, captions flag duplication of headings), which explains the purpose of the type field beyond its basic enum description. The optional `goals` and `system` parameters are already clearly said to be for traceability, so no further compensation is 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 opens with a specific verb and resource ('Evaluate an array of content items') and enumerates the accepted types. It differentiates itself from the closest sibling by stating it is used for per-item content verdicts rather than the principle library, so an agent can distinguish it clearly without inspecting schemas.
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 says 'Use this instead of evaluate_design when you need per-item content verdicts rather than the principle library,' providing a direct alternative and condition. It also signals 'Pure offline — no network or browser,' which helps an agent decide when the tool can be safely invoked.
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?
It discloses a lot beyond the annotations: upsert semantics, carried-forward behavior for omitted fields and clearing for explicit empty values, live capture of references, consistency checks that produce consistency_warnings, build_hints for expensive techniques, and the enforced refusal when no calibration content results. Even with destructiveHint and idempotentHint=false in annotations, the description adds concrete failure modes and mutation semantics. The behavior is described in enough specificity that the agent can predict side effects before calling.
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 text is long and dense, but it is coherently organized around core purpose, then upsert semantics, then build hints, then enforcement/escape hatch. Almost every sentence adds a new behavioral fact, though a few clauses repeat details already present in the schema. It is not short, but it earns most of its length given the complexity of a 9-parameter, nested-object write operation.
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 no output schema, the description thoroughly covers what the result carries: consistency warnings, carried_forward fields, build_hints, refusal errors, and how audit_taste later uses the binding. It also covers edge cases like re-binding, uncalibrated_ack carry-forward, explicit empty clears, and consistency-checking against captured references. The most important pitfalls are all front of the agent: persistence location, refusal conditions, and post-bind effects.
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?
The schema is fully covered, but the description still adds high-value parameter nuance beyond field names: that references are not prose but captured live and consistency-checked against design_notes, that overrides use 'off' to silence a rule, that design_notes keys are normalized and trimmed dimension names, and that uncalibrated_ack is an escape hatch with strict gatekeeping. It tells the agent how parameters combine and what result they inform. This goes well above the baseline 3 one would expect for 100% 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 opens with a precise verb and object — 'Persist a project's surface calibration for a taste profile' — and immediately ties the input to the outputs of get_taste_interview. It distinguishes the tool from siblings like audit_taste by explaining that this is the binding step, not the audit application step. It also enumerates exactly what is stored (surface, hosts, overrides, voice_note, design_notes, references), leaving no ambiguity about the tool's role.
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 gives an explicit workflow: 'Run get_taste_interview, ask the USER, and bind their answers.' It also names audit_taste as the later step that consumes the binding, and warns against using uncalibrated_ack as a workaround. The escape hatch is precisely scoped to users who were interviewed and deliberately skipped every dimension, which is strong when-versus-when-not guidance.
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 signal destructive behavior, but the description goes further by specifying the profile can be overwritten, where it is stored, how the storage directory can be overridden, the merge order of template vs explicit rules, and that the operation is local-first with nothing leaving the machine.
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 dense but every sentence earns its place. It front-loads the core action before diving into format details, and organizes the complexity in a single cohesive flow rather than padding with filler. The exclusions and caveats are integrated without repetition.
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 create/overwrite tool without an output schema, this description is complete: it covers accepted inputs, markdown rules format, template bootstrap, precedence/merge order, storage location, overriding the directory, and necessary follow-up steps. The addition of a warning against non-rule-shaped docs contextual makes this especially strong.
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?
Even with 100% schema coverage, the description meaningfully enriches parameter semantics: it explains markdown ingestion syntax, severity marker conventions, rule delegation syntax, scope markers, negative-prompt behavior, and template merge order. This goes well beyond the raw JSON 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 opens with a precise verb and resource: 'Create (or overwrite) a named taste profile'. It then defines what a taste profile is, where it is persisted, and how it differs from related concepts like getting or interviewing a taste profile, making the tool's 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 gives explicit input-mode guidance: pass rules[], pass markdown, or pass a template. It tells the agent when the template is appropriate, warns that brand-story docs should not be ingested, and explicitly says to run get_taste_interview afterward because a template is a floor, not a substitute for calibration.
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

Raven MCP MCP server – quality and maintenance score on Glama

Copy to your README.md:

[![Raven MCP MCP server – quality and maintenance score on Glama](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 – quality and maintenance score on Glama](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