Raven

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

Description adds behavioral context beyond annotations: 'pure offline, no browser/network'. It states corpus-modal inference which is not present in the annotations. No contradictions with annotations; annotations carry readOnlyHint, openWorldHint=false, idempotentHint=true, destructiveHint=false, but the description adds significant offline/no-network behavior and return summary detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Information-dense single-paragraph description with semicolon-separated enumerations; each clause carries details (score semantics, per-page extraction, references). However, the density is a bit high and structuring a few bullets would aid; no wasteful sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description fully specifies return values: per-page extraction, consistency dimensions with references, issue list with outlier names, score formats, summary formats. It also specifies edge-case behavior (when token omitted and flags). This is detailed and complete for invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and required parameters are fully described. Description adds a behavioral note about the inference of a default canonical value from a corpus when token is omitted. This is nuanced and does not directly explain each parameter in a way that is especially necessary, so the baseline is 3, lifted for the added inference context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description has a specific verb ('Audit') + resource ('multiple pages for cross-page consistency') + scope ('content-container width and hero heading tier'), and distinguishes from sibling tools by referencing the 'issue #9 single-blob blind spot' and 'pages that each pass audit_page'. Highly specific and clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description gives explicit requirements (≥2 pages with {name, html}) and explicitly calls out the alternative usage context (corpus modal inference when no token supplied) but does not explicitly state when to use this tool vs siblings like audit_page or audit_contrast. Context is clear, exclusions are not.

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

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

The description discloses the exact output format (per-item pass/warn/fail, principle ids, concrete issues, before→after rewrite, aggregate summary) and the nature of the heuristics (robs requires number+unit, CTA length constraints). It also states it is completely offline, which the annotations do not mention. Annotations already mark readOnly/idempotent, so this extra context enhances trustworthiness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, dense sentence that compresses a good deal of information—output, heuristics, and alternatives—without superfluous words. It could be split into a second sentence for readability, but it is clearly structured and earns its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is read-only, has no output schema, and has intricate behavioral rules, the description suffices: it specifies what is returned, the nature of the heuristics, and even the no-network constraint. It lacks explicit error-handling or batch-size limits, but these are not critical for a self-contained auditing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds heuristic–type mapping (e.g., 'metric items must carry a number+unit', 'prose flags passive voice'), which explains how the type parameter influences evaluation. However, it does not add code-level detail for goals or system beyond what the schema states, so it stays at the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Evaluate') and resource ('an array of content items... against UX-writing principles'), and explicitly distinguishes it from sibling 'evaluate_design' by specifying that this tool provides per-item verdicts rather than the principle library.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'Use this instead of evaluate_design when you need per-item content verdicts', giving an explicit alternative and a specific condition. It also notes the tool is 'Pure offline — no network run or browser', but it does not enumerate scenarios where the tool should NOT be used beyond that single distinction.

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

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

Read-only annotations already tell the agent this is non-destructive, but the description adds genuinely important behavior: url mode omits passing per-element rows, returns counts plus aa_failures/indeterminate_bg_rows, and explains why to prevent misinterpretation. This is exactly the kind of output-trait disclosure agents need beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is dense but appropriately sized for a tool with two modes and complex output omission behavior. The core purpose and input choice are front-loaded, and the rationale for omitting passing elements is not wasted, though the middle sentence is long and mixes a pitch with technical spec.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: thresholds, actionable rows, indeterminate-bg rows, mode-specific output, and intentional omission. An agent can form accurate expectations about both the result size and correctness of interpretation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the property descriptions already explain url, screenshot, and dom_snapshot. The main description adds one crucial cross-property meaning: url and dom_snapshot are alternative input modes, and each mode implies different output semantics, which is not expressed in the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action and resource: compute WCAG contrast ratios for all text elements, using either a rendered page or a supplied dom_snapshot. It clearly distinguishes this from the many audit_* siblings by focusing on contrast measurement and reporting pass/fail plus actionable ratios.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context for both usage modes: pass a url to audit a real page or pass a dom_snapshot when elements are pre-collected. It does not explicitly state which sibling tools to use instead in other cases, so it stops just 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.

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

Annotations already declare readOnly/idempotent/non-destructive behavior, so the bar is lower. The description adds what is analyzed, but it does not disclose the output/response format, error behavior, or any caveats about required color/contrast inputs; with no output schema the return shape is unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose and an efficient em-dash list of checks; the input shape is stated compactly. No filler or redundant phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has nested inputs and no output schema, and the description covers input enough to invoke, but it leaves the return value unspecified and fails to mention the minTarget option. For a scoring tool without an output schema, a bit more output/options context would be needed for full agent autonomy.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema_description_coverage of 0%, the description must compensate. It names the required elements structure and viewport and gives purpose to fields (e.g., rect for tap targets, fgColor/bgColor for contrast), but it omits the optional options.minTarget parameter entirely and does not explain parameter value semantics beyond repeating property names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action ('Score an accessibility-enriched iOS element snapshot') and enumerates the exact checks (labels/values/traits, tap targets, WCAG contrast, Dynamic Type clipping, VoiceOver order), clearly distinguishing it from narrower sibling audits like audit_contrast or audit_tap_targets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It indicates the tool applies to iOS accessibility snapshots produced by the AccessibilitySnapshot XCUITest/ios-capture harness, giving clear context for when to invoke it. It does not explicitly name alternatives or say 'do not use for other snapshot types,' but the iOS/XCUITest framing is enough to imply the intended scope.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description aligns by stating it 'Reads' inputs. It adds meaningful behavioral detail beyond the annotations: the specific audit checks (contradiction detection, unused permissions, ATS exceptions, secrets, data-egress) and the OR-requirement between Info.plist and app.json.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-structured: a purpose sentence, an input sentence, and a flag list. It is longer than typical but each clause adds information, and the main verb is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and five optional parameters, the description covers the tool's behavior well. It mentions the return shape via 'Same return shape as audit_page' and lists the major audit categories, making it usable for an agent. Minor gap: no explicit mention of error cases or format requirements for the XML/JSON inputs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter is individually documented. The description adds inter-parameter context: it explains that Info.plist and app.json are mutually exclusive alternatives, and that 'source' enables code-vs-declaration checks, which is beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Audit') and resource ('iOS or React Native/Expo app's privacy posture') and clearly differentiates from sibling audit_* tools by focusing on privacy concerns like NS*UsageDescription strings, entitlements, and data-egress paths.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly identifies the intended use case ('for App Review and user trust') and input requirements (Info.plist OR app.json, with optional PRIVACY.md, entitlements, source). However, it does not explicitly name alternatives or exclusion criteria, so it stops short of the highest rating.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description adds meaningful behavioral context: screenshot pixels are not decoded for scoring, iOS secondaryLabel/tertiaryLabel are treated as platform-standard and produce warnings rather than failures, taste-profile bindings are unavailable on the hosted endpoint, and the return shape matches audit_page. These are non-obvious traits an agent needs to know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: purpose, alias relation, no-arg behavior, concrete input shape, scoring dimensions, return shape, and endpoint limitation. It is front-loaded with the primary purpose and avoids redundant restatement of schema properties.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter tool with nested objects and no output schema, the description is remarkably complete. It tells the agent how to discover the snapshot shape, what the scoring covers, what the return shape is, and how to avoid project/profile complications. The optional screenshot's role is also clarified sufficiently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds extra meaning by showing the expected call shape, defining what the elements array is scored against (44×44pt targets, contrast, visual rhythm in points), and clarifying that omitting project/profile yields the stateless audit. This enriches the schema without needing to repeat every field definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Audit a rendered iOS screen from a view-hierarchy/accessibility snapshot'. It further distinguishes itself by stating it is an alias of audit_screen with platform:"ios", and enumerates concrete checks (44×44pt touch targets, contrast, visual rhythm), which separates it from generic audit_screen and iOS-specific sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit invocation guidance: call with no arguments for the expected snapshot shape, call with the elements/viewport object to run the audit, and omit project/profile for a stateless run. It names audit_screen as the generic alternative, though it does not explicitly state when not to use audit_ios_screen versus related siblings like audit_ios_a11y or audit_ios_privacy.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond those flags: the no-arg call returns a pasteable snippet, the snippet prints {elements, viewport} JSON, and the second call yields the actual audit scores. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no wasted words, and the main action is front-loaded. Each sentence covers a distinct aspect: what the tool evaluates, how to use it, and when it is relevant relative to audit_page.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a specialized two-call audit tool with no output schema, but the description offers enough to use it correctly. It covers the required invocation sequence, the expected data interchange format, the dimensions being scored, and the intended rendered-page use case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes elements and viewport with 100% coverage, so the baseline is 3. The description is worth credit because it explains how those parameters are obtained and used ('Call with no arguments to get a DevTools snippet... Call again with that JSON'), connecting the schema's params to a concrete workflow and removing ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Evaluate visual rhythm from a rendered page's geometry,' which names a specific verb and resource. It then lists the concrete outputs ('alignment, gap-rhythm, and optical-balance scores') and explicitly positions itself as the complement to audit_page for things only visible once rendered, clearly differentiating from its most relevant sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete two-phase workflow: call with no arguments to receive a DevTools snippet, then call again with the snippet's JSON to obtain the scores. It correctly orients the tool toward rendered-page context by noting it is for 'things only visible once rendered,' though it does not enumerate exclusions for every other audit sibling.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, and the description complements them by explaining the remote endpoint restriction (url rejected, html required), the return contract (pass/fail per check with fix instructions), and the token-aware behavior of containerMaxWidth. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded with the core purpose and check list. However, the remote endpoint note is repeated three times ('url argument is REJECTED', 'url-capture is disabled', 'pass html instead'), which adds redundant padding and reduces conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with no output schema, the description provides a clear scope, check list, return behavior, and endpoint-specific invocation caveat, making it sufficient for selection. It does not need to detail output formatting since compact/schema covers that, but it could have mentioned the screenshot behavior; overall it is complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 89%, and the schema already fully describes parameters like url, html, strict, compact, viewport, interactions, scroll_settle, containerMaxWidth, adversarial_verify. The description adds little beyond restating containerMaxWidth's token-aware behavior and the remote url rejection, which are already in schema; thus it stays near the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Audit HTML/CSS against Raven's design quality standards' and enumerates specific check categories (typography, accessibility, responsive patterns, style guide compliance, visual rhythm), which clearly defines the tool's resource and scope. It distinguishes itself from sibling tools like audit_typography or audit_contrast by being a comprehensive page-level audit covering multiple standards.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes operational guidance for the containerMaxWidth parameter and explicitly states the remote endpoint requires html instead of url. However, it does not provide explicit when-to-use or when-not-to-use criteria or name alternatives (e.g., use audit_typography for typography-only checks), so it stops short of a 5.

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

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

Annotations already declare read-only, non-destructive, idempotent behavior. The description adds value by specifying the per-relation match/mismatch/uncertain output and illustrating a typical drift case, with no contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence packs purpose, relationship types, output semantics, and a motivating example without unnecessary filler. The em-dash example is illustrative and earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the core contract: inputs (snapshots + checklist), behavior (comparison against named relationships), and outputs (per-relation match/mismatch/uncertain). It lacks an explicit return-value structure but is sufficient for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description summarizes ios/android as {elements, viewport} and checklist as an array, and lists supported spatial relations. Still, it leaves checklist item 'a'/'b' reference semantics and tolerance behavior unexplained, requiring inference from schema field names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific comparison (iOS vs Android element snapshots) against a checklist of spatial relationships and explicitly mentions output categories (match/mismatch/uncertain). It clearly differentiates from sibling audit tools by focusing on cross-platform layout drift.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete usage scenario (status text centered on one platform but top-aligned on the other) and states required inputs, making invocation conditions clear. However, it does not explicitly contrast with sibling tools like audit_consistency or audit_layout.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations: it explains detection mechanisms, the categorization logic the tool performs, and the environment requirement of headless chromium.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is composed of information-dense sentences with no filler. It front-loads the main action, then adds categorization, output format, and environment requirements in a natural and efficient order.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description compensates by specifying the returned table and its columns. Annotations cover side-effect safety, and the tool's environment requirement is disclosed, making it complete enough for an agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and each parameter already has meaningful descriptions for URL, breakpoints, and viewport height. The description reinforces the audit's purpose but does not meaningfully extend parameter-level semantics beyond what the schema documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific operation: render a URL at multiple breakpoints and flag elements visible on desktop but hidden on mobile. It also defines the categories ('likely-oversight' vs 'intentional') and output columns, making it clearly distinct from sibling audit tools in the same family.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage context is clear: it applies when auditing responsive visibility for content that disappears on mobile. It names a practical environment prerequisite (headless chromium), though it does not explicitly list alternatives or say when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict these. It adds valuable context beyond annotations: specific checks performed (accessibilityLabel, hitSlop, allowFontScaling, etc.), what is rewarded, a limitation on taste-profile bindings on the hosted endpoint, and a pointer to audit_page for return shape. This is a solid disclosure without being overwhelming.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but packs every sentence with distinct, useful information: scope, specific checks, exclusions, return-shape pointer, and hosted limitation. No filler or redundancy. It is denser than the mid-tier examples but not bloated for a tool of this complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 params, no output schema), the description covers purpose, input types, exclusion boundaries, and behavioral limits. It leverages the sibling audit_page for return shape ('Same return shape as audit_page'), which is an efficient reference. It does not detail every return field, but that is acceptable given the pointer to a known sibling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% parameter descriptions, so the description need not repeat them. It does add a meaningful semantic: omitting both project and profile yields a stateless audit, which clarifies the default behavior in a way the schema does not. This is a minor enhancement over the baseline, so a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Audit React Native / Expo source (JSX/TSX + StyleSheet) against the iOS HIG + Android Material conventions RN must satisfy.' It further distinguishes from siblings by stating 'RN-native checks only — no web/CSS or SwiftUI rules' and explicitly contrasting with audit_ios_screen ('scores the rendered screen'). This makes 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states what the tool is NOT for ('no web/CSS or SwiftUI rules') and directs users to audit_ios_screen for rendered screens, effectively providing an alternative. It also gives a practical usage tip: 'Omit project/profile to run the stateless React Native audit.' However, it does not explicitly enumerate sibling use cases beyond these two, so it stops short of full when-to-use guidance.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context beyond annotations: platform-specific scoring thresholds (44pt vs 48dp), Android warning relaxation ('onSurfaceVariant/outline = warn not fail'), the hosted-endpoint limitation on taste-profile bindings, and that the screenshot is only for the caller's reference since 'Geometry is scored from the snapshot, not decoded pixels.' 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Seven sentences, each earning its place: purpose, self-discovery hint, platform behavior, scoring scope, return reference, endpoint limitation, and stateless usage. Front-loaded with purpose, no filler or redundancy with the schema fields. This is dense but efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter tool with nested objects (elements, viewport) and no output schema, the description covers purpose, platform behavior, scoring scope, return shape (delegated to audit_page reference), and a key limitation. The 'Same return shape as audit_page' shortcut assumes agent knowledge of that sibling, but the self-discovery instruction ('Call with no arguments') provides a fallback for both input shape and capture method. Reasonably complete for the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 86% schema coverage the baseline is 3. The description goes beyond the schema by explaining the behavioral impact of platform (threshold and semantic-role differences), the meaning of omitting project/profile (stateless run; profile bindings unavailable remotely), and the self-documenting hint 'Call with no arguments for the expected snapshot shape' for elements. This adds genuine semantic value the schema's field descriptions don't provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb-resource pair: 'Audit a rendered mobile screen (iOS or Android) from a view-hierarchy/accessibility snapshot.' It further disambiguates from the many audit_* siblings by scoping exactly what is scored ('touch targets, contrast, and visual rhythm') and by referencing the analogous 'Same return shape as audit_page,' making the tool's distinct role clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives actionable invocation guidance: 'Call with no arguments for the expected snapshot shape,' explains when to pass platform:"android" vs the iOS default, and notes 'Omit project/profile to run the stateless screen audit.' It does not explicitly name alternatives or state when NOT to use this tool over sibling audit_* tools, but the platform and binding trade-offs are well covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond that: what the tool flags and rewards, that it returns pass/fail with fix instructions, and that taste-profile bindings are unavailable on the hosted endpoint. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: purpose, specific checks, rewards, scope exclusion, return format, and endpoint limitation. It is front-loaded with the core purpose and then provides necessary detail without filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, no output schema, and rich input schema, the description covers the essential context: what is checked, what is rewarded, return format, platform scope, and remote-endpoint limitations. It could be slightly more explicit about strict-mode grading, but the schema already covers that parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly. The description adds some useful context about the stateless mode and hosted-endpoint limitation, but it does not significantly expand on parameter semantics beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Audit SwiftUI source against Apple's Human Interface Guidelines.' It then enumerates concrete checks (fonts, colors, accent color, tap targets, spacing) and explicitly scopes itself to iOS-native SwiftUI, distinguishing it 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: it is for SwiftUI/iOS only, explicitly excludes web/CSS rules, and explains when to omit 'project'/'profile' to run the stateless audit. It does not name specific sibling alternatives, but the platform/framework scoping is enough to guide selection.

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

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

The description adds significant behavioral context beyond the annotations: it uses headless Chromium, measures with real getBoundingClientRect values, filters elements below the threshold, emits concrete CSS fixes, tells exactly what fields appear, and sorts worst-first. It also clearly distinguishes the browser mode from the pure snapshot mode, which is important for an agent predicting side effects. No contradiction with the annotations was found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but highly organized, front-loaded with purpose in the first clause, followed by a clear actor list and a structured output specification. The two-mode sentence elegantly distinguishes use cases without forcing the agent to open the schema or infer behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-output-schema tool, the description fully specifies the return format, the threshold criteria, the element coverage, the sorting, and the two possible invocation modes. The absence of an output schema is compensated for well by this exposition. The only implicit rule is that url and elements should be treated as exclusive modes, but the wording strongly implies this.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema coverage is 100%, the description materially enriches every parameter: url is tied to browser rendering, elements is tied to the no-render snapshot pathway, and minSize default of 44px is restated and connected to the WCAG/Apple requirement. It explains when each parameter is relevant and how they differ in execution, beyond the literal schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb plus resource: a WCAG 2.5.5 / Apple 44pt tap-target audit for web pages. It goes further by enumerating which element types are collected and exactly what the per-element output contains, making its scope unambiguous and easily distinguished from sibling audits like audit_contrast or audit_ios_a11y.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear operational guidance with two explicit invocation modes: pass a url for real headless chromium measurement, or pass a pre-collected elements snapshot when a browser should not be involved. It also states the 'for the web' context, but it does not explicitly name sibling alternatives for native/mobile audits or state when this tool should not be used.

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

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

While the annotations already indicate a read-only, harmless operation, the description adds critical behavioral context by revealing endpoint-specific limitations (URL capture disabled) and disclosing the operational constraint that 'nodes' is the only supported input in this environment. It could have been a 5 but the description is somewhat verbose in its repetition of the URL warning, and it doesn't disclose any potential performance considerations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is information-dense but somewhat bloated with repetition: the URL-disabled warning appears twice, and the caveat could have been stated once cleanly. The opening sentence is front-loaded, but the repeated 'audit_typography url-capture is disabled on the hosted (remote) endpoint. Pass a 'nodes' snapshot instead of 'url'.' is redundant duplication.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity with an array input with nested properties, both the description and schema work together to cover the two parameters completely. The description compensates for potential misuse by the super-user (URL) being unavailable, and the output structure is clearly defined. The sibling differentiator (audit_page) is also named.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with a clear description for each of the two parameters. The description itself adds conceptual rationale for 'nodes' by explaining it's for pre-collected snapshots, but the main semantic value of the parameter purpose comes from the schema. The description primarily repeats the URL rejection warning already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it audits typographic scale with three specific checks (modular scale, line-height, weight ladder) and names the sibling tool (audit_page) it extends. The inclusion of output structure and the explicit scoping to nodes vs URL further clarify its exact purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells users when to use this tool (to go beyond audit_page's pass/fail checks) and provides a strong, repeated warning that URL mode is disabled on the hosted endpoint and that nodes should be passed instead. This is excellent when-not-to-use guidance considering the schema already documents each parameter in detail.

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

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

Annotations already declare readOnlyHint/idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description layers substantial disclosure beyond that: headless-chromium requirement, disabled-on-hosted behavior with concrete measurements, scroll-settle/video-play semantics (fires whileInView, plays preload=none videos), and the three-tier evidence tagging. No contradiction with annotations — an audit tool reads and reports, consistent with readOnly=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The best information is front-loaded into the first sentence (render-and-capture, live URL, viewports×themes), with operational details and limitations following in a logical cascade. It is dense, but every sentence carries unique value — cost, environment, alternatives, output contract — making the length justifiable for a tool this complex.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description owns the return contract and fulfills it: 'Every finding is tagged confirmed | likely-artifact | inconclusive with its evidence, ranked by severity'. It covers prerequisites (headless chromium), environment constraints (disabled on hosted with timing evidence), resource cost (~95–120s), and a fallback path (audit_page for static HTML), leaving no material question answered for the caller.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3; the description meaningfully adds by explaining why behaviors matter (interactions are 'diffed against baseline to catch hover/click white-wash', scroll_settle 'fires reveal-on-scroll/IntersectionObserver content'). Only minor gap: the compact vs includeScreenshots false-default tension and their combined use is implicit rather than explicitly called out.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a concrete verb+resource ('Layer 0 render-and-capture audit') and specifies exact scope: LIVE URL, viewport×theme matrix, scroll-settling, optional interactions, real pixels + rendered DOM. Actively differentiates from siblings by naming the exact class of bugs it catches ('cropped images, blank videos, hover white-wash, sliced exports, hidden-on-mobile') that are 'invisible to HTML-string/geometry audits', cleanly separating it from audit_page, audit_contrast, and audit_layout.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use ('This is the tool that catches real-world visual nits...'), an explicit alternative for static input ('pass the page HTML to audit_page here for a static grade'), and deployment-specific instruction ('Run it locally instead (npx raven-mcp) where there is no request deadline'). Measured cost data (95s cheapest, >120s defaults) lets an agent reason about whether the call is worth the budget.

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

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

The description goes beyond the readOnly/idempotent annotations by disclosing the actual mechanism: headless Chromium rendering, play attempts, currentTime sampling, and classification with reasons. It also clarifies that the dom_snapshot path avoids a browser entirely, which is meaningful behavioral context that the annotations do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences cover the mechanism, the value proposition, and the usage modes with no wasted words. The front-loaded sentence immediately explains the tool's behavior and classification output, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete enough for an agent to correctly choose and aim this tool: it explains what happens, what it catches, and which parameter path to use. Its exact return shape is not described in detail, but the classification categories are named, and with no output schema, the coverage of behavior and parameters is strong enough to support a solid call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% parameter descriptions, giving a baseline of 3. The description adds mode-level semantics beyond the schema: url means render and observe, while dom_snapshot means classify pre-collected observations without rendering. This improves the agent's understanding of how parameters relate to different execution paths.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: audit video playback by rendering a page and observing whether videos advance. It clearly distinguishes itself from static audit siblings by focusing on actual currentTime movement and classifying clips into playing|paused|stalled|empty|error.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives strong context by noting this tool catches black/non-playing videos that static audits miss, and it provides clear routing between the two operating modes: url for browser-based rendering or dom_snapshot for deterministic classification without a browser. It does not name sibling tools explicitly or state when not to use it, but the use context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive read/query operation. The description adds minimal behavioral context beyond the example; it doesn't mention output format details or any side effects, but that is fine given the read-only nature. Without annotations, it would score lower, but with them, 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with two clear sentences: the first states the purpose, the second provides a concrete example. There is no unnecessary redundancy. It is appropriately sized and front-loaded with the core action. The example slightly increases length but adds significant clarity, so a 4 is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (two parameters, one required, with clear schema and annotations), the description is adequate but not highly informative. The output schema is missing, so the description could have explained what the composite output looks like or mentioned that the format parameter controls output. However, the tool is simple enough that a 3 is reasonable; it covers the main purpose but lacks some behavioral detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters (compositions, format) are fully described in the JSON schema. The description adds the crucial concept of 'mixing tokens' and gives an example, which helps understand the 'compositions' parameter. However, since the schema already explains the structure and enums, the description's extra value is moderate. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Mix tokens from different design systems to create a custom composite.' This distinguishes it from related tools like generate_design_system or get_design_system, which are about creating or retrieving systems, not composing across systems. A concrete example is provided, enhancing clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete example of when to use it, but does not explicitly state when not to use it or mention alternatives. However, the sibling tool names (e.g., generate_design_system, get_design_system) offer some implicit context, and the example implies composition use cases. There is no explicit guidance on where this fits in a workflow, so it falls short of a 4.

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

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

The annotations already declare readOnly, idempotent, and non-destructive hints. The description adds important context beyond annotations: the pixel-diff functionality is disabled on the remote endpoint, which changes tool behavior depending on endpoint, and it explains why (unbounded image decode). It also clarifies that passing a description makes the call stateless, which is useful operational knowledge. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact—four sentences that front-load the core action and outputs, then a contextual warning and a clear alternate usage mode. There is no filler; every sentence contributes. It is well structured and immediately understandable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a six-parameter all-optional tool with no output schema, the description covers the essential behavior: it tells what the tool returns, how to invoke it statelessly, and the main caveat about the remote endpoint. The schema describes each parameter individually, so the description covers the high-level contexts. It does not fully address what happens when both screenshot and description are provided, but this is a minor ambiguity given that the description explicitly directs to omit screenshots for the description mode.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With full schema coverage (100%), the baseline is 3. The description compensates by explaining a key relationship among parameters: 'Omit before_screenshot/after_screenshot and pass a description to evaluate the design against UX principles statelessly.' It also directly refers to the primary parameter (description) and its role. This adds a usage constraint not present in the schema's individual parameter descriptions, raising the value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Evaluate a design description against UX principles' and details the outputs (relevant principles, violations, suggestions). It clearly distinguishes from kindred 'audit_*' and 'get_*' siblings by centering on generic design evaluation with both description and screenshot input pathways.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete usage direction: omit screenshots and pass a description to evaluate statelessly on the remote endpoint. It does not explicitly name alternatives but the two modes are clearly contrasted, and the limitation of the remote endpoint is stated, which effectively says when screenshots are not appropriate. No exclusions are mentioned, but the intent is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat safety traits. It adds useful context about the auto-generation of a harmonious palette from a brand color and notes that the HTML export is a self-contained page for stakeholders, which goes beyond the structured data without contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, both information-dense and free of filler. The first sentence states the core function, and the second highlights the standout feature (self-contained HTML export). It's front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (6 params, multiple export formats), the description covers the generation and export options but fails to mention what the tool actually returns (e.g., a file, URL, or inline content). Since there's no output schema, this gap leaves the agent uncertain about the response format, though the description is otherwise adequate for a read-only generation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter is already documented. The description reiterates some points (brand color auto-generates palette, style preset influences spacing) but does not add substantial meaning beyond what's in the schema. It summarizes the workflow but doesn't introduce new parameter-specific details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to generate a complete, custom design system with a full token set. It specifies inputs (brand color, style preset) and output formats, distinguishing it from siblings like get_design_system (which likely retrieves existing systems) and compose_system.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for creating new design systems but does not explicitly mention when to avoid it or when to use alternatives like get_design_system or compose_system. While the context is clear, there's no explicit guidance on alternatives or scenarios where this tool should not be used.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by detailing the two rendering modes, the line of interaction, and side-by-side ideal-state output. It does not contradict any annotation and provides meaningful beyond-annotation detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one comprehensive paragraph that front-loads the core purpose, then systematically explains modes and options. It uses numbered modes and parenthetical examples for clarity. Every sentence contributes substantive information without unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (nested objects, dual modes, optional ideal-state) and the absence of an output schema, the description covers the essential usage rules and output format (self-contained HTML page). It clarifies the two-actor conditional based on `actors` presence and the side-by-side ideal-state feature. Some depth (e.g., exact rendering details) is left to the schema, but the description is adequate for agent selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are well-documented in the schema. The description adds relational meaning (e.g., how `actors` switches layout, how `ideal` activates side-by-side) that goes beyond individual parameter descriptions. It explains the semantic difference between single-actor and two-actor usage, which the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool renders a service blueprint as a self-contained HTML page, specifying two distinct modes (classic Shostack and two-actor HI-loop) with concrete examples (customer ↔ lawyer, etc.). This is a specific verb+resource+output format and clearly differentiates from sibling audit/get/list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains when to use each mode (e.g., 'when `actors` is supplied, renders two swim lanes') and the optional ideal-state side-by-side rendering. It does not explicitly mention alternatives or when not to use the tool, but the context makes it clear this is a generation tool distinct from audits and knowledge lookups.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate safety. It does add context about the content returned (specific principle areas). However, it doesn't discuss response structure or any potential limitations. Given the annotations cover the safety profile, this is adequate but not exceptional.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise paragraph that front-loads the core purpose and then provides usage context. It is efficient with no redundant fluff, though it could be slightly shortened without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking an output schema, the description conveys what the tool returns (principles across specified topics) and how to invoke it with the optional topic filter. The overall context is sufficient for a simple read-only retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with both 'topic' and 'format' fully described. The description lists example topics (logo, gradient, imagery) which mirrors the schema's enumerated values, adding no new information. Per the baseline for high schema coverage, 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Get brand and visual-design principles' and enumerates specific subtopics (logo usage, gradient usage, imagery, visual hierarchy, brand-as-system). This is specific and resource-oriented. While it doesn't explicitly contrast with sibling tools like get_brand_system or get_principles, the specificity of the content makes the purpose clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides usage guidance: 'Use when the user asks about branding, logos, gradients, imagery, visual consistency, or how to treat a brand across surfaces.' This tells the agent when to invoke the tool. It does not mention exclusions or alternatives, but the guidance 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.

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat safety. The description adds the behavior of matching against 12 systems and providing the closest match, which is valuable beyond annotations. However, it does not disclose specifics like how 'closest match' is determined or potential variations, which is a minor gap given no 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, concise and front-loaded with the primary action. It includes a concrete example and hints at the output. No redundant phrasing; each sentence adds value. Slightly verbose with the 'Matches against 12...' detail could be trimmed but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, full schema coverage, and annotations (readOnly, idempotent), the description covers the essential purpose and provides examples. It doesn't explain return values, but there is no output schema and annotations suggest a safe read operation. The mention of 'implementation instructions' and ready-to-use CSS gives a good sense of what to expect. A minor gap is not specifying limitations of the 12 systems, but it's adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context about the overall purpose and mentions the company (e.g., Spotify) but does not add detailed meaning for 'mode' or 'format' beyond what the schema provides. The description could elaborate on default behaviors or how format affects output, but it meets the baseline for full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a complete design system for a specified company (e.g., Spotify) and returns token set, style guide, and CSS. It distinguishes from siblings like get_design_system and get_brand_principles by focusing on 'branding like a specific company' and providing ready-to-use CSS, though it could be more explicit about sibling differences.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an example of when to use it ('Make me an app with branding like Spotify') and mentions it matches against 12 known systems, implying the use case. It doesn't explicitly state when NOT to use it or mention alternatives like get_design_system, but the context is clear enough for an agent to infer suitable scenarios.

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

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

Annotations already declare readOnly and idempotent hints, so safety is covered. The description adds non-annotation context: trends are time-stamped, suggesting they evolve, and it explicitly warns not to treat them as prescriptive. It also lists specific included trend categories, giving a clear picture of the output without overpromising. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the main purpose, then examples, and closes with a critical caveat. Every part earns its place, with no redundancy or fluff. It's ideal in length and structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema informational tool, the description is fully complete. It states what it returns (trends with time stamps), enumerates examples, and explains how to interpret them (calibration not prescription). No additional context is needed for an agent to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description correctly avoids any parameter talk. The schema is trivially complete, and the description adds no parameter-related confusion. Baseline score of 4 applies due to zero params, and the description does not need to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states exactly what the tool does: retrieves current brand and visual-design trends, with specific examples of trend types. It clearly differentiates from sibling tools like audit_* or get_brand_principles by focusing on real-time trend calibration rather than audits or brand system definitions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context by noting trends are 'time-stamped' and should be 'treated as a calibration signal, not a prescription', implying use for design inspiration or validation. However, it doesn't explicitly state when to use this over alternate tools like get_brand_principles or list_creative_models, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict these. The description adds useful scope information but does not disclose output behavior beyond the coverage list, such as how stage filtering affects results or whether responses are template-based.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short, front-loaded sentences. The first states the core purpose, and the second expands scope without redundancy or filler, earning its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity, full schema coverage, and strong annotations, the description is largely sufficient. It omits explicit mention of optional stage filtering, but the schema's enum description covers that, and the return concept of 'strategies' is implied by the verb 'Get'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the type and stage parameters. The description's list of coverage areas loosely reinforces the type enum values but adds no new parameter syntax, constraints, or behavioral details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pairing ('Get business and monetization strategies for digital products') and then enumerates the exact content areas covered. This clearly distinguishes the tool from sibling get_* tools focused on brands, patterns, research methods, or design systems.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance or mention of alternatives such as get_metrics_framework. However, the second sentence implies applicable scenarios by listing monetization, retention, onboarding, growth, and metrics topics, giving the agent a reasonable sense of when to select this tool.

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

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

The annotations already disclose this is read-only, idempotent, non-destructive, and not open-world. The description complements this by adding that the return value contains 'actionable yes/no items', implying a deterministic, side-effect-free response. There is no contradiction; the description's 'get/returns' language aligns with readOnlyHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a tight two-sentence structure where each sentence earns its place: the first states the action and resource, and the second states the return shape. There is no fluff or redundancy, and the most important verb-resource pairing is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only, 2-parameter tool with an extensive schema and a clear output format described in the second sentence, the information package is largely complete. The one gap is the exact data structure of the returned checklist; however, the description's 'yes/no items' gives a functional sense of the shape, which is sufficient for this tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Since the input schema describes 100% of the parameters and even provides rich context (e.g., the 'platform' enum explains the differences between 'ios' and 'react-native'), the description carries no responsibility to repeat this. This meets the baseline, and the description itself adds no further value beyond the schema, which is appropriate here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The phrase "Get a pre-publish checklist" pairs a specific verb with a well-scoped resource, and the clarification that it "returns actionable yes/no items to verify before shipping" fully spells out the tool's function. This clearly distinguishes the tool from its many audit_* siblings (e.g., audit_screen, search_knowledge), which perform actual analysis or lookups rather than retrieving a verification checklist.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description effectively conveys that this is the go-to for pre-shipping verification of a UI type, and the contrast with the audit_* tools is implied by the phrase 'before shipping'. However, it doesn't explicitly name alternatives (e.g., 'use audit_* to run an audit') or give explicit when-not-to-use guidance, leaving a small window for an agent to select a sibling against intent.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds transparency about expected return content (do's/don'ts, examples, evidence, checklist), which is valuable since there is no output schema. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the verb 'Get', no fluff, and all information is relevant and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with one enum parameter, the description provides sufficient guidance: what it returns, the categories, and the content structure. The absence of an output schema makes the description's return-item listing essential and complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single 'type' parameter is fully documented in the schema with an enum, and the description restates the categories in natural language. This adds minimal meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: retrieving content design patterns for specific UX copy types. It lists the return contents (do's/don'ts, examples, evidence, checklist) and distinguishes it from sibling tools like get_content_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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by enumerating the four pattern types (error messages, empty-state, notifications, form validation), allowing an agent to infer when to use it. It does not explicitly mention alternative tools or exclusions, but the scope is well-defined.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds context about the content topics covered, enriching what the tool returns beyond the annotation basics, 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the purpose and example topics. It is concise and every sentence adds value, wasting no words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the safe annotations, and full schema coverage, the description is adequate. It does not describe the output structure (no output schema exists), but the nature of the tool—a list of principles—is implied by the examples. It could briefly mention how the 'format' parameter affects output, but the schema covers that. This is complete enough for a simple read operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters, with detailed descriptions for 'context' and 'format' already present. The tool description adds little new meaning—it mentions filtering by context but does not elaborate beyond the schema. Baseline 3 applies because the schema fully documents parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves UX-writing principles and lists specific topics (clarity, active voice, error-message anatomy, etc.), which differentiates it from siblings like get_principles or get_brand_principles. The verb 'get' and resource 'UX-writing principles' are specific and non-tautological.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool by offering a filter by writing context (e.g., 'error messages'), making it clear the tool is for obtaining writing guidance. However, it does not explicitly state when not to use it or mention alternatives such as get_content_pattern, so there is some room for ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so no need to repeat safety. The description adds the scope of content returned, which is useful. However, it does not disclose behavior like whether 'all' is the default, how sections are returned, or if the response includes examples, but this is minor given annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, dense sentence that lists all major content components without fluff. It is front-loaded with the action and resource ('Get a brand's content design system') and efficiently enumerates the sections. No redundant or wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 100% schema coverage and a simple 2-parameter tool, the description is quite complete. It covers what the tool returns. However, it does not mention that 'section' defaults to 'all' (though the schema does), and there is no output schema, so agents might not know the exact structure. Given the tool's moderate complexity and good schema, this is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all parameters with detailed descriptions (id example, section enum with explicit values and default). The description adds meaning by explaining the content of the system, but it doesn't elaborate on the section parameter (e.g., what each section includes), which the schema already describes. Given 100% schema coverage, baseline 3, and the description adds some context about the tool's purpose, a 4 is justified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a brand's content design system, listing specific components (voice attributes, tone shifts, vocabulary, grammar rules, content patterns, inclusive language). This distinguishes it from siblings like get_content_pattern (which likely returns a single pattern) and get_design_system (which likely covers visual design).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving brand content guidelines, and the list of sections suggests when to use section filters. However, it does not explicitly state when to use this over get_content_principles or get_brand_system, which might overlap. No direct exclusions or alternatives are named.

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

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

With annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the safety profile is well-covered. The description adds that the tool 'Returns customer problem statement, ideal state, hypothesis, LOFA, and experiment templates,' which explains the composition of the response beyond what annotations state. However, no additional behavioral constraints like rate limits, authentication requirements, or response format details 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action and audience ('Design for Delight (D4D) framework templates') followed by specifics about what's returned. 'structured product thinking' adds some flavor but is somewhat generic. Overall, efficient and focused, with minimal fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given this is a simple read-only tool with a single optional parameter (100% schema coverage) and a safe annotation profile (read-only, idempotent, non-destructive), the description is mostly complete. It identifies what's returned. Someminor gaps exist: no examples of usage, and no explicit statement that it returns all templates (vs. a subset) without filters, which would help round out the context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including descriptive text for the 'stage' parameter and its enum values. The description's mention of templates is generic and doesn't substantially add to the schema's own documentation. Baseline 3 is appropriate here since the schema handles the documentation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets D4D framework templates: 'customer problem statement, ideal state, hypothesis, LOFA, and experiment templates.' It uses a specific verb ('Get') and resource ('D4D framework templates'). While siblings like get_design_system and get_content_pattern exist, the description's focus on D4D distinguishes it, though it could be stronger in explicitly contrasting with these similar tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says it's 'for structured product thinking,' implying a context of use but provides no explicit when/when-not guidance or alternatives. Context signals show 49 sibling tools like get_design_system and get_content_pattern, suggesting related frameworks exist, but the description doesn't help an agent decide between them. The usage guidance is implicit ('structured product thinking') rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds value by specifying the output formats and token groups, which are behavioral details not in the annotations. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the purpose and lists the key token categories and formats. No wasted words; every element adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (3 params, no output schema, no nested objects) and the strong annotations, the description is complete enough. It covers the resource, the token groups, and the output formats. It could mention default behavior (e.g., default format is dtcg) but that is already in the schema. Overall, adequate for the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (id, group, format) are already documented in the schema. The description adds minimal extra meaning beyond the schema, but it does clarify the output formats and token groups, which aligns with the parameter descriptions. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves design tokens for a specific design system, listing the token categories (colors, typography, spacing, etc.) and available output formats (W3C DTCG, CSS custom properties, flat). This distinguishes it from sibling tools like get_brand_system or get_content_system, which target different resource types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying the resource (design system) and the optional filters (group, format), but it does not explicitly state when to use this tool versus alternatives like list_design_systems or generate_design_system. However, the context is clear enough for an agent to infer the appropriate use case.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it returns structure, when-to-use, pitfalls, and examples, which provides some output context but not much beyond annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at two sentences, front-loaded with the core purpose. Every sentence adds value—the first lists contents, the second gives usage triggers. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool with only two params, no output schema, and rich annotations, the description is complete. It tells the user what they get (structure, when-to-use, pitfalls, examples) and when to use it, which is sufficient for this scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with both 'id' and 'search' fully described in the schema. The description does not add any additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves product-metrics frameworks and lists the specific frameworks (HEART, AARRR, etc.), which distinguishes it from siblings like get_business_strategy or get_checklist. The verb 'get' plus resource 'product-metrics framework' is specific, and the usage intent is clearly conveyed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Use when the user asks how should we measure success? or what metrics should we track?' This is clear context. It does not mention when not to use or alternatives, so it falls short of a 5 but is still strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, lowering the transparency burden. The description adds value by disclosing the return content (do's, don'ts, evidence, and checklists), which is important since there is no output schema to carry that information. No contradiction exists between the description and annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero wasted words. The first sentence front-loads the core purpose and the second efficiently enumerates supported pattern types. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with 3 well-documented parameters, robust annotations, and no output schema, the description is reasonably complete: it states the return format (do's, don'ts, evidence, checklists) and the full domain of pattern types. Slightly more detail on filtering behavior or output structure would push it to a 5, but it is adequate as-is.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with all three parameters (type, goal, platform) already documented and two having enums, so the baseline of 3 applies. The description adds no parameter-specific meaning beyond what the schema provides, such as example values or format details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb+resource construction ('Get proven UI/UX patterns for a specific design type') and enumerates 13 concrete pattern types (signup flows, pricing pages, dashboards, etc.), making the tool's scope unmistakable. This enumeration implicitly differentiates it from sibling tools like get_content_pattern, get_service_pattern, and get_checklist by specifying exactly which UI/UX pattern domains it covers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description establishes clear usage context by defining the tool as a pattern reference for specific design types and stating what it returns (do's, don'ts, evidence, checklists). However, it does not explicitly name alternatives or provide when-not-to-use guidance relative to siblings such as get_checklist or get_design_system, stopping short of the top score.

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

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

Annotations mark readOnly, idempotent, and non-destructive, matching the absence of side effects. However, the description does not explicitly state that no mutations occur, and it only adds minimal context, so a moderate score is warranted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is compact but information-dense with bullet-like structure: scoped intro, parameters inline, and line-separated fields. Clear front-loaded purpose. No redundant API details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Four parameters (one required) with 100% documented schema and rich enum descriptions, but no output schema, no return-value description, and no elaboration of output format beyond the stated variants. Also no nested structures.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers all four parameters with rich descriptions for each: context ('what you're designing'), format ('full/checklist/brief'), category (filtering knowledge areas), and platform ('web/ios/react-native' with platform-specific behaviors). This goes beyond the schema's raw types/enums by giving design-context guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action and resource ('Get design principles relevant to a UI context') and enumerates concrete knowledge areas (usability heuristics, UX laws, Gestalt principles, accessibility, typography, color theory). It is distinct from sibling tools like get_design_system or get_brand_principles, but does not explicitly name alternatives or exclusions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description conveys 'for design decisions, grounded in design principles,' but does not explicitly state when not to use the tool or name alternatives like get_content_system, get_design_system, or audit_contrast. It provides clear context though.

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

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

Annotations already mark this as read-only and idempotent, covering safety. The description adds value by disclosing what the tool returns (protocols, do/don't guidance, evidence, checklist) and implying it is a non-mutating lookup. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the main verb and resource, then efficiently enumerates categories with examples. Every segment adds value, with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple lookup tool with two optional params and clear annotations, the description covers the essential: what it returns, examples of content, and when to use. No output schema is needed, and the description is sufficient 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.

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 enhances parameter understanding by listing concrete method examples under each category, which clarifies what the 'category' enum values represent and hints at the scope of 'search'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's function: 'Get research method details' with specific categories (qualitative, quantitative, usability) and example methods. This distinguishes it from sibling tools like audit or brand-related tools. The return values (protocols, guidance, evidence, checklist) further clarify purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage context: 'Use when the user is designing a study or asking how to measure something.' It does not mention when not to use or name alternative tools, but the guidance is direct and actionable.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive operation. The description adds value beyond annotations by detailing what the response includes: patterns, do/don't guidance, evidence, and a checklist. This gives the agent an accurate expectation of the tool's output without relying on 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loads the core purpose, and includes both the expected output and usage conditions. There is no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple retrieval tool with one parameter, strong annotations, and no output schema. The description provides the key decision context, the pattern values, and the return contents, making it complete for an agent to select and invoke the tool appropriately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of the single parameter 'type' with an enum and description. The tool description adds complementary semantic value by listing the pattern names and linking them to design scenarios, helping the agent map user intent to the correct enum value beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets a service design pattern and enumerates the supported types (e.g., service blueprinting, human handoff, omnichannel continuity). It also indicates the return content (patterns, do/don't guidance, evidence, checklist), distinguishing it from generic get_pattern and generation tools like generate_service_blueprint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear 'Use when...' clause covering service flow design, escalation, cross-channel experience, and moment of truth. It does not explicitly mention alternatives or exclusion criteria, but the listed sibling tools and pattern-type enumeration make the intended use reasonably discoverable.

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

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

Annotations indicate `readOnlyHint: true`, `idempotentHint: true`, and `destructiveHint: false`, so it's a safe, read-only operation already declared. The description adds context on what the tool returns (the 14 points) and frames its utility as a general checklist, which is useful behavioral information. While annotations already set the safety profile, the description enriches understanding of the tool's purpose, though it could mention whether it returns the entire list or filters by request—minor deduction given the strong annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, information-dense sentence that front-loads the core purpose ('Get the GOV.UK Service Standard'), then explains what that is (14 points for service readiness) and why it matters (rigorous checklist). It includes a usage hint ('when the user asks how to evaluate a whole service') without any fluff. Every clause earns its place—extremely economical and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a parameterless, read-only tool with no output schema and rich annotations. The description covers what the tool does, its scope, and when to use it. There's no additional complexity (nested objects, enums, required fields) that would demand more explanation. The description is complete for an agent to select and invoke the tool correctly. The query about return values is preemptively answered by explaining the standard's content.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters and 100% schema coverage (empty schema), the tool has no parameters to document. The description appropriately uses 'Get' to indicate a no-argument retrieval, and the schema trivially handles this. No compensation needed, but the description's clarity about what the tool does (returns the Service Standard) is the most relevant information an agent needs to know.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description is clear and specific, using a direct 'gets' verb to indicate the action, and clearly names the resource 'GOV.UK Service Standard'. It explicitly defines the tool's scope regarding the 14 points for UK government service assessments, which helps distinguish it from siblings like 'generate_service_blueprint', 'get_design_system', 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use the tool: 'when the user asks how to evaluate a whole service.' While it doesn't name direct alternatives, the description implies when this tool is more appropriate than others (i.e., for holistic service evaluation rather than specific audits or design systems), which aligns with the siblings listed. The phrase 'beyond government' expands its applicability, clarifying it's not limited to UK-government-related queries.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's non-mutating nature is covered. The description adds no further behavioral context (e.g., result format, pagination, or permissions), but given the strong annotation baseline and minimal tool complexity, a score of 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, reasonably sized sentence that is front-loaded with the action and resource. The parenthetical list of examples is slightly redundant, but overall it is efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with zero required parameters, a search/filter pair defined in the schema, and no output schema, the description is sufficiently complete for how an agent would invoke the tool. It identifies the subject, the available actions, and a few concrete examples, leaving no critical clarity gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema fully describes both parameters: 'search' and 'category' with their own descriptions and category enumerate values. The description's mention of 'Filter by category or search by name' merely restates the schema without adding new insights, so it gains no bonus.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Browse available content design systems' and identifies the resource as 'brand voice and tone guides', with specific examples. It distinguishes itself from sibling tools like list_design_systems and get_content_system by focusing on content systems, and mentions the supported filter/search actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear context of when to use the tool: when you want to browse or search available content design systems, with filtering options. However, it does not explicitly mention alternatives or when not to use it, so it lacks the full exclusionary guidance that would earn a 5.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructiveness, and the description broadens understanding by explaining that entries list typical inputs and best-for guidance. This adds contextual value without repeating annotation properties; there is no hint of pagination or full result-set behavior, but that is not critical for a low-risk catalog browse.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with the key action front-loaded. It avoids redundant phrasing and includes only high-signal information about catalog scope and entry content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, two optional filters, and rich annotations, the description provides adequate context for a read-only browse operation. It explains what an entry contains and the capability areas covered, leaving the filtering behavior to the schema. A slightly richer note about default result behavior could push it higher.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers 100% of parameters with useful descriptions and enum examples, so the description does not need to re-explain them. The description adds broader context about capability categories, but it does not materially enhance the parameter-level understanding beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource as Raven's creative model catalog and the action as browsing it. It also names the covered modalities (image, video, 3D, audio, etc.), which helps an agent understand the scope, though it does not explicitly contrast itself with sibling tools like list_creative_presets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied by 'Browse Raven's... creative model catalog,' so an agent can infer this is for exploring available model capability slots. However, no explicit guidance is given on when to choose this over related list_* tools, such as list_creative_presets or list_design_systems.

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

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

Annotations already declare read-only and non-destructive behavior. The description adds contextual value by specifying the scope of presets (product photoshoots, UGC ads, etc.), which helps the agent understand what results to expect. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one concise sentence, front-loaded with the verb 'Browse' and the resource, followed by a specific list of preset categories. No filler or redundant info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with no output schema, the description sufficiently explains the tool's scope and what it returns (creative presets related to various production types). It does not mention pagination or response format, but for a basic listing operation this is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters (search and media_type) are fully described in the schema, so the description adds no additional parameter semantics. Per the rubric, with 100% schema coverage, the baseline is 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists Raven creative presets and enumerates the specific categories (product photoshoots, marketplace cards, UGC ads, etc.), making the purpose unambiguous. It easily distinguishes from sibling tools like list_design_systems or list_creative_models.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description conveys the tool is for browsing presets but gives no explicit guidance on when to prefer it over alternatives or when not to use it. The listing of preset types implies applicability, but there's no exclusionary or comparative language.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read behavior is covered. The description adds scope/category context but doesn't disclose additional behavior like pagination, result limit, or how saved user systems are handled beyond what the schema itself states.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded sentences with no filler. Every phrase adds value: what the tool does, the token context, possible filters, and search capability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, optional-filter read-only list tool, the description and annotations are sufficient to select and invoke it. A fully complete answer would mention result details/pagination, but for this tool's complexity and schema richness the absence is not a significant gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%; both parameters are described clearly in the input schema, including all category values and the 'user' saved-system note. The description repeats filter modes but adds almost no new semantic information beyond the schema, so baseline score is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Browse') and names the resource ('available design systems'), along with the subject area ('for tokens') and optional filter methods. This makes the tool's purpose clear and distinguishes it from sibling audit/get tools, though it does not explicitly differentiate from the similar list_content_systems.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The sentence directly tells the user when to use the tool: to browse available design systems and refine by category or name. It gives clear context and filter options, though it lacks explicit 'when-not-to-use' commentary or named alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is clear. The description adds valuable non-annotation context: the scoring model is a transparent heuristic (not a proprietary black-box), and the endpoint's lack of per-user state. This discloses behavioral constraints that the schema and annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with high information density. The first sentence covers the purpose and scoring dimensions, the second reveals the heuristic nature, and the third provides the critical operational caveat. No filler words, no restating of parameter names that are already in the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is mostly complete given the simplicity of the tool (single required param, no output schema, no nested objects). It covers purpose, exceptions, and parameter handling. Minor gap: it does not describe the scoring output format (e.g., numeric scores per dimension, an overall score, or qualitative feedback), which an agent may need to know to parse the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds important parameter semantics for 'brand_profile_id' (local-only, remote-unavailable, omit for stateless) and clarifies 'creative_text' meaning (prompt, script, ad copy, or concept). It does not add detail on 'channel' or 'audience', but the schema already describes them adequately, and the description adds value for the trickiest parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Score') and explicitly enumerates the resource types (creative prompt, script, ad concept) and the seven evaluation dimensions (hook strength, benefit clarity, product signal, CTA, channel fit, audience fit, brand fit). It further distinguishes itself from sibling tools like evaluate_design and score_page by clarifying the scoring is a transparent heuristic, not a proprietary model, which clarifies its unique purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage context: local brand profiles are not available on the hosted remote endpoint, and per-user state is a later phase. It instructs the agent to omit 'brand_profile_id' for stateless scoring, which is a clear when/how directive. This goes beyond implied usage and gives actionable selection guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds meaningful context beyond them: scores are 'derived deterministically from the same checks as audit_page', no browser is launched, and the url argument is actively REJECTED (not silently ignored) on the hosted endpoint. This rejection behavior and determinism are genuinely additive and consistent with the idempotent hint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a strong purpose statement, but the final two sentences repeat what was already stated in the third sentence: 'score_page url-capture is disabled on the hosted (remote) endpoint. Pass the page HTML via the "html" argument instead' restates 'Pass html directly; the url argument is REJECTED on this hosted (remote) endpoint.' The phrase 'hosted (remote) endpoint' also appears three times, making the description longer than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description carries the burden of documenting return values, and it does so thoroughly: 7 category scores (0–10), overall 0–100 score, A–D grade, weakest category, and the three non-mechanical categories with tool guidance. Combined with the strong parameter schema and safety annotations, the tool is fully comprehensible; it only misses an example or more concrete detail on the guidance for brand/conversion/motion tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each parameter (url, html, strict, containerMaxWidth) already has a detailed schema description including the hosted-endpoint rejection of url. The description adds emphasis by pointing to html as the correct input, but contributes little semantic information beyond what the schema already provides, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific, actionable statement: 'Score an HTML/CSS page across 7 design categories' with each category enumerated and its 0–10 rating scale stated. It clearly distinguishes from siblings by explicitly referencing audit_page ('same checks as audit_page') and noting it covers categories Raven does not mechanically assess, differentiating it from both the audit_* family and score_creative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: use this tool for deterministic scoring 'no browser required' versus audit_page (which presumably renders). It names audit_page as the direct alternative, provides the hosted-vs-local usage split ('Pass html directly; the url argument is REJECTED on this hosted (remote) endpoint'), and even directs users toward other tools for brand/conversion/motion categories.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description adds the cross-category scope but no further behavioral details like pagination or result ordering, so it meets the lower bar without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The first sentence states the verb and scope, the second gives usage guidance. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple search tool with two well-documented parameters and read-only annotations, the description fully supports selection and invocation. It explains what it searches, when to use it, and the schema covers parameter details, so no critical information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: both 'query' and 'layer' have clear descriptions with examples and enum explanations. The tool description adds no additional parameter meaning beyond what the schema already provides, matching the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches across design principles, UI patterns, and business strategies, which is a specific verb+resource scope. It distinguishes itself from the sibling getters and audit tools by serving as the catch-all search when the category is unknown.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: 'Use when you need to find specific guidance or don't know which category to look in.' This implies more specialized tools are better when the category is known, though no alternatives are named.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context with 'Pure offline math' and details the computation: 'computes the smallest foreground adjustment (and an alternative background adjustment) that reaches AA/AAA — with the achieved ratio and direction.' No contradiction; it supplements the annotation hints well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, each earning its place. The first sentence states purpose and algorithm, the second describes outputs, and the third connects to audit_contrast and alternative approaches. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with nested object parameters and no output schema, the description covers input context (failing pairs), behavior (online math, minimal adjustments), and output characteristics (achieved ratio and direction). It stops short of fully specifying the output object structure, but the combination of schema and this description is sufficient for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 reinforces that inputs are 'failing' pairs and mentions 'target ratio'/'level', but it does not add significant meaning beyond what the schema's own parameter descriptions already provide. The added value is minimal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's function: 'Given failing WCAG color pairs, return the MINIMAL color change that clears the target ratio.' This is a specific verb+resource+outcome. It also references the sibling tool audit_contrast, distinguishing it as the remediation counterpart to the audit tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear when-to-use guidance by stating 'Feeds directly from audit_contrast's failing pairs: pass them here to get concrete passing values instead of brute-forcing colors by hand.' This names an alternative (manual brute-forcing) and the intended workflow, though it does not explicitly list when-not-to-use scenarios.

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