Raven

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

The description goes well beyond the readOnlyHint and idempotentHint annotations by disclosing that the tool is pure offline with no browser or network, that it infers the canonical modal value when no token is supplied, and that it flags silent cross-page disagreements. This gives meaningful context about how the audit behaves, not just what it returns.

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

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

The description is compact and well-organized: purpose, input contract, behavioral notes, blind-spot warning, then return summary. Every sentence contributes unique value, and the most important facts are front-loaded.

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

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

Despite having no output schema, the description clearly enumerates what the tool returns: per-page extraction, consistency dimensions, outliers, issues, score, and summary. It gives an agent enough context to confidently invoke the tool and interpret the result without further lookups.

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

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

The schema already describes all parameters, including the semantic difference between supplied tokens and corpus-modal inference. The description adds useful guidance about collecting pages from different routes and not needing the design token in advance, but it doesn't significantly expand on the individual parameter formats beyond the schema.

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

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

The description states a specific verb and resource: audit multiple pages for cross-page consistency of container width and hero heading tier. It clearly differentiates itself from audit_page by naming the issue #9 single-blob blind spot where pages each pass individually but disagree with each other.

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

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

The description tells the agent to pass ≥2 pages collected from different routes on the same site, making the primary use case explicit. It references audit_page as the related single-page tool, but it does not fully spell out all when-not conditions or explicitly compare against the wider set of audit siblings.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description goes much further by disclosing the exact return shape (per-item pass/warn/fail verdicts, matched principle ids, concrete issues, before→after rewrite, aggregate summary), the deterministic heuristic rules per content type, and the offline execution model. There is no contradiction with the annotations.

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

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

Every sentence carries information: purpose, return format, heuristics, offline behavior, and a sibling-pointer. The content is packed but not repetitive, and it is front-loaded with the core purpose before the details. Nothing is extraneous.

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

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

The tool has 3 parameters, no output schema, and a large sibling set, but a call agent can invoke it correctly. The description covers the input domain, the heuristics, the return value, the offline behavior, and the alternative tool condition. Any missing details, such as array size limits, are nonessential for a read-only deterministic audit tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics on top by tying each `items.type` enum value to the heuristic that applies (e.g. metric must carry a number+unit, CTA/label action-led and ≤4 words, captions flag duplication of headings), which explains the purpose of the type field beyond its basic enum description. The optional `goals` and `system` parameters are already clearly said to be for traceability, so no further compensation is needed.

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

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

The description opens with a specific verb and resource ('Evaluate an array of content items') and enumerates the accepted types. It differentiates itself from the closest sibling by stating it is used for per-item content verdicts rather than the principle library, so an agent can distinguish it clearly without inspecting schemas.

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

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

The description explicitly says 'Use this instead of evaluate_design when you need per-item content verdicts rather than the principle library,' providing a direct alternative and condition. It also signals 'Pure offline — no network or browser,' which helps an agent decide when the tool can be safely invoked.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes far beyond these by revealing a genuine non-obvious behavior: url mode OMITS per-element rows for passing elements and explains why (typical page generates hundreds of thousands of characters of them). It also describes the two-mode return shape difference, determinism between input modes, and overload since with manual computing — exactly the behavioral detail an agent needs to set output expectations.

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

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

Every clause in the description earns its place — scope, thresholds, failure semantics, mode differentiation, and the rationale for omission are all loaded with concrete facts. The text is dense and readable, though it is a run-on multi-clause paragraph with dashes and commas that could be crisper as separate structured sentences, which costs it a point toward full conciseness.

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

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

With no output schema present, the description still communicates per-mode return shapes, the specific failure row categories (aa_failures, indeterminate_bg_rows), and the omission behavior that affects downstream processing — a near-complete picture for an analysis tool. Minor leftover ambiguities are the aggregation details of 'counts' and how AAA failures are explicitly represented in url mode, so slightly more mandated detail would reach 5.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents each parameter. The description adds real semantic value above that by encoding what each option produces, e.g. url mode yields aggregated counts plus only action rows whereas dom_snapshot yields a per-element mapping, and it distinguishes the analytical purpose of the inputs. It stops short of describing format details per parameter, so 4 rather than 5.

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

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

The description states a precise verb and resource: 'Compute WCAG contrast ratios for every text element' from a URL or a dom_snapshot, and spells out the concrete output (AA 4.5:1/3:1 and AAA pass/fail, failing pairs with selector, ratio, delta-to-pass). This makes it immediately differentiable from look-alike siblings like audit_contract or suggest_contrast_fix without needing to open any schema.

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

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

The description clearly defines the two invocation routes and what each returns — 'dom_snapshot mode returns a row per supplied element; url mode returns counts plus every row that needs action — so an agent knows which input to use in which situation. It also implies the intended use case ('replacing manual eyedropper + ratio math'), but it does not explicitly state exclusion cases or point to an alternative sibling for other needs, such as suggest_contrast_fix for remedies.

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

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

Given the annotations already declare readOnlyHint=true and idempotentHint=true, the description adds behavioral value by enumerating exactly what is analyzed and how the input should be captured. It makes clear this tool consumes ready-made snapshot data and does not generate it, which is useful behavioral context beyond the safety annotations.

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

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

The description is compact and well-structured: it opens with the action, then summarizes the audit checks, and closes with the exact input shape and capture mechanism. The inline list is a little long, but each part carries operational meaning and there is no filler or repetition.

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

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

For a nested complex schema with no output schema or param descriptions, the description covers the main input contract exceptionally well but leaves gaps: no description of return/output format, no explanation of the 'options.minTarget' field, and no units for colors or fields. These omissions leave an agent needing to guess some behavior despite the otherwise rich scaffold.

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

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

The description explicitly lists the main required fields (elements, viewport, and the nested element attributes) and therefore gives useful semantics for the core parameters. However, the optional 'options' parameter and its 'minTarget' field are completely unexplained, and there are no descriptions inside the schema, so the tool doesn't provide complete parameter-level guidance.

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

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

The description clearly states the tool's operation: 'Score an accessibility-enriched iOS element snapshot' followed by the specific audits it performs (missing labels, tap target sizes, WCAG contrast, Dynamic Type clipping, VoiceOver order). This is specific enough to distinguish it from sibling audit tools such as audit_ios_screen or audit_contrast even without their schema.

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

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

The description clearly indicates it should be used when an accessibility-enriched element snapshot is available and refers to the capture method ('via the AccessibilitySnapshot XCUITest / ios-capture harness'). It does not explicitly name alternative tools or state when not to use it, but the specific resource and capture requirement make the use case evident.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description reinforces this by saying it 'Reads' inputs rather than mutating anything. It adds meaningful behavioral scope: what is inspected (Info.plist, app.json, PRIVACY.md, entitlements, source), and what kinds of issues are flagged. It also notes 'Same return shape as audit_page,' which gives return-consistency context. No contradiction with annotations.

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

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

The description is dense yet well-structured: it leads with the purpose, then input alternatives, optional inputs, flag categories, and finally return-shape consistency. Despite its length, every phrase contributes to the agent's ability to select and invoke the tool correctly. There is no filler or restatement of the name.

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

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

Given the tool's complexity (multiple input formats, optional cross-references, many detection categories) and the absence of an output schema, the description provides strong contextual coverage. It states what the tool reads, what it flags, and that it matches the return shape of audit_page. It leaves the exact return structure implicit by referencing audit_page, which is acceptable but not a full output description.

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

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

The input schema already describes and covers all five parameters, so baseline is 3. The description adds key semantics above the schema: it clarifies that managed Expo apps have no Info.plist, that source enables code-vs-declaration contradiction checks, and that transient fields like expo.ios.infoPlist, expo.android.permissions, plugins, and extra are audited. This adds meaningful guidance for how the parameters are used together, supporting a 4.

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

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

The description opens with a specific verb and resource: 'Audit an iOS or React Native/Expo app's privacy posture for App Review and user trust.' It precisely names the audit domain and differentiates itself from general-purpose audit siblings like audit_page, audit_ios_a11y, and audit_asset_integrity by focusing on privacy posture.

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

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

The description establishes clear when-to-use context: for an iOS/React Native/Expo app's privacy posture in App Review and user trust contexts. It explains that a native Info.plist OR an Expo app.json is read, plus optional supplementary files. It does not explicitly name alternative tools or give exclusion conditions (e.g., 'use audit_ios_a11y if auditing accessibility instead'), but the use case is unambiguous.

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

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 cover read-only, non-destructive, and idempotent behavior. The description adds meaningful context beyond that: the two-phase interaction, the snippet-based capture flow, the printed JSON shape, and the score categories. It stops short of defining the score output structure, but the core behavior is well disclosed.

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

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

Three sentences carry the full workflow with no filler. The purpose comes first, then the two-step invocation, then the sibling relationship. Every sentence earns its place.

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

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

For a tool with no output schema, the description handles the main gaps well: it names the outputs of both calls and clarifies when to use it relative to audit_page. Some specificity about score shape is absent, but an agent can select and invoke the tool correctly with the information given.

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

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

The schema already documents the top-level parameters thoroughly (100% coverage), so the description is not required to repeat field semantics. However, it does add useful workflow meaning by tying 'that JSON' to the DevTools snippet output and making it clear the same object should be passed back. This is enough to maintain the baseline 3.

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

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

The description names a specific verb and resource: 'Evaluate visual rhythm from a rendered page's geometry.' It also distinguishes itself from audit_page by being 'the complement to audit_page for things only visible once rendered,' which prevents confusion among many audit_* siblings.

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

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

The description gives an explicit call protocol: call with no arguments to get the DevTools snippet, then call again with the JSON that snippet emits. It also names audit_page as the alternative and scopes this tool to rendered geometry, so the agent knows exactly when this tool is appropriate.

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

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it produces per-relation match/mismatch/uncertain verdicts and gives a concrete layout-drift example. No contradiction with annotations exists.

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

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

Two sentences with no filler: the first front-loads the core compare-and-flag behavior and the second concisely tells the caller what inputs to provide. The parenthetical enumerations are dense but necessary for disambiguation.

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

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

The description is complete for a read-only comparison tool given its complex nested schema and absence of an output schema: it defines both inputs and the categories of output verdicts. A minor gap is that the relationship checklist's a/b element references and tolerance semantics are left implicit, but the overall context is adequate for correct invocation.

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

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

With 0% schema description coverage, the description compensates by naming all top-level parameters (ios, android, checklist) and their broad shapes, and by enumerating the checklist relation domain (vertical centering, baseline/left alignment, equal gap/size, presence, truncation). It does not fully explain what a/b represent or how tolerance is used, but the schema structure plus this context is enough for a competent agent.

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

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

The description uses a specific verb ('Compare') alongside a clear resource ('iOS vs Android element snapshots') and explicitly names the expected output ('flag per-relation match/mismatch/uncertain'). The cross-platform scope distinguishes it from sibling audit tools such as audit_ios_screen or audit_page without ambiguity.

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

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

The description clearly states what should be provided ('Provide ios+android {elements,viewport} snapshots and a checklist[]') and includes an example that signals when the tool is appropriate (cross-platform layout drift detection). It does not explicitly name sibling alternatives to avoid, but the use case is well implied.

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

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

With readOnlyHint, idempotentHint, and destructiveHint=false annotations already covering the safety profile, the description adds meaningful behavioral detail: it performs a real browser render, requires headless chromium, categorizes flags into 'likely-oversight' versus 'intentional', and returns a table with specified columns. This gives the agent a clear mental model of what will happen and what comes back.

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

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

The description is three sentences with no fluff: first sentence states the action and detection mechanism, second explains the categorization, third states the output shape and a hard requirement. It front-loads the core purpose while every sentence earns its place.

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

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

Despite having no output schema, the description discloses the output table columns, the distinction the tool draws, the technical prerequisite, and the operation. Combined with the annotations and fully described parameters, an agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the parameters URL, breakpoints, and viewportHeight are already fully documented in the schema. The description only adds that URLs are rendered at multiple breakpoints, which does not materially extend parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific action ('flag content elements that are visible on desktop but hidden on mobile') against a specific resource (a rendered URL) and enumerates the exact CSS conditions it checks. It also distinguishes this audit from general audit siblings by naming the hidden-on-mobile content bug it targets.

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

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

The description makes the intended use case explicit: auditing a URL across breakpoints for content that disappears on mobile, with a clear environment prerequisite (headless chromium). It does not explicitly name sibling alternatives or say when not to use the tool, but the use case is specific enough that an agent can recognize when it applies.

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

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 annotations already establish that this is safe, read-only, open-world, and idempotent, and the description adds meaningful behavioral detail beyond that: it uses headless Chromium and real getBoundingClientRect when a url is provided, is fully non-rendering in elements mode, requires headless Chromium for url mode, and returns a sorted worst-first fix table. It describes the output table fields in enough detail without an output schema.

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

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

The description is dense but efficient: it lists the affected element selectors, the output columns, the CRUCIAL behavior difference between the two modes, and the default threshold. There is no filler or repetition from the schema. Every sentence contributes a distinct piece of information an agent needs.

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

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

For a tool with no output schema and only annotations, this description covers everything: what gets audited, what the audit emits, what measurements mean, the minimum-size default, the two accepted input modes, and the environmental requirement (headless chromium for url). It is fully actionable for an agent deciding whether to call the tool and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is already 3. The description adds extra value by explaining that url triggers rendering and measurement, while elements is a pure no-browser mode, and by explicitly stating the 44px default that minSize controls. This goes beyond what the schema says without being overly verbose.

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

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

The description names the specific audit standard (WCAG 2.5.5 / Apple 44pt), the exact resource being audited (web interactive elements), and the concrete output (per-element fix table). It clearly differentiates this from the many sibling audit tools because it is specifically about tap-target dimensions and proposes CSS fixes.

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

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

The description gives clear guidance on when to use each input mode: pass a url for real headless-chromium rendering plus measurement, or pass pre-collected elements[] for a pure, no-browser snapshot audit. It does not explicitly state when to choose this over sibling alternatives like audit_ios_a11y or audit_page, so it stops just short of full routing guidance.

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

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, lowering the bar. The description adds genuinely valuable behavioral context beyond annotations: it uses headless Chromium, samples currentTime before and after a play() attempt, and produces a classification. It fully explains the two paths (live render vs. deterministic classification) and contradicts nothing.

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

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

Three sentences, all dense with distinct information: the mechanism (multiply, currentTime, play attempt + classification set), the value proposition (catches what static audits miss, with domain context), and the parameter usage. Every sentence earns its place; nothing is repeated from the schema.

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

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

The description compensates well for the lack of an output schema by naming the classification categories and the observation method. It covers both potential invocation paths. The remaining gap is the exact return format (how classifications and reasons are represented) — but with a well-endowed schema and read-only annotations, the overall context is complete enough for a capable agent.

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

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

Schema coverage is 100%, so the schema already documents all three parameters (url, observeMs, dom_snapshot) with detail. The description goes beyond schema by revealing that url and dom_snapshot are alternative, mutually exclusive entry points — one requires a browser render, the other is a deterministic path without a browser. That relationship is not in the schema and is materially useful to an agent.

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

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

The description names a specific verb/resource pair ('render a page... observe whether each <video> actually advances') and precisely delimits the output: each clip classified into playing|paused|stalled|empty|error with a reason. It clearly distinguishes itself from static audit siblings, which it claims to complement by catching black/non-playing videos that static audits miss.

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

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

The description provides a clear usage context ('catches black/non-playing videos that static audits miss — the most common real-world defect on marketing sites with video content'), which is an implicit when-to-use signal against static audit alternatives. It also explains the two calling modes within the tool: url-based rendering and snappable deterministic dom_snapshot input. It does not name a specific alternative tool and does not state when NOT to use it, so it is not a 5.

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

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

The annotations already convey readOnly, idempotent, and non-destructive behavior. The description adds the useful mental model of mixing systems but not additional behavioral detail such as output shape, invalid pair handling, or system ID lookup behavior. No contradiction with annotations.

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

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

The description is short and front-loaded: one sentence defines the purpose and one sentence provides a clarifying example. No redundancy or decorative wording.

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

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

With full input schema coverage, robust annotations, and a clear format enum, the description is complete enough for an agent to select and invoke the tool. It could be marginally stronger by explicitly noting the output is a token composition or bundle, but nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents the compositions array, system IDs, groups, and format enum. The description's example adds value by mapping a concrete use case to the parameter model: 'Linear's colors + Stripe's typography' translates directly to compositions pairs. It doesn't describe format further, but the schema already does.

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

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

The description states a specific action ('Mix tokens from different design systems') and a concrete result ('create a custom composite'). The example 'Linear's colors + Stripe's typography' makes the resource and scope immediately clear, and distinguishes it from sibling tools like get_design_system or generate_design_system.

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

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

The description gives clear context for when to use this tool: when combining tokens across independent design systems. It does not explicitly name alternatives or state when not to use it, but the combination-focused purpose is unambiguous enough for selection.

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

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 signal read-only, idempotent, non-destructive behavior, so the description is not required to duplicate that. It adds useful behavioral detail by specifying that the output is a self-contained HTML page, that two-actor rendering creates a line of interaction between the swim lanes, and that ideal-state mode changes the output to side-by-side. No contradictions with annotations.

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

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

The description is compact and front-loaded: the first sentence states the core behavior, and the rest only explains mode selection and optional behavior. Examples like 'customer ↔ lawyer' are immediately clarifying rather than synthetic fat, and nothing is repeated unnecessarily.

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

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

For a rendering tool with nested parameters and no output schema, the description sufficiently communicates what is generated, when actors are needed, and how the optional ideal state changes the result. It could also describe more edge behavior, but the mode explanations and schema documentation jointly make the tool practically usable.

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

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

The schema covers all parameters with descriptions, so the baseline is at 3. The description adds value by interpreting `actors` as the runtime switch between two fundamentally different rendering modes and by clarifying that `ideal` triggers a side-by-side comparison. This semantic guidance goes beyond a field-by-field schema listing.

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

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

The description names the deliverable explicitly — a self-contained HTML service blueprint — and the main verb is specific: 'Render'. It also distinguishes two supported modes (single-actor Shostack and two-actor HI-loop), so an agent can quickly tell what this tool does and how its forms differ.

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

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

The description gives a clear condition for choosing a mode: omit `actors` for classic single-actor rendering, provide `actors` for the two-swim-lane layout, and optionally provide an ideal-state for side-by-side rendering. It does not explicitly compare against sibling tools or give 'when-not-to-use' guidance, but the mode selection rules are concrete and decision-ready.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile of the operation. The description adds no significant behavioral details beyond that (no return format, no requirement stipulations). No contradiction is present, so a neutral 3 is appropriate.

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

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

The description is two sentences, front-loaded with the core resource and purpose, followed by a concise usage trigger sentence. The enumerated lists are dense but each item adds semantic nuance that the schema does not fully convey, so no sentence is wasted.

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

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

For a read-only, zero-required-params tool with no output schema, the description's identification of topics plus usage triggers is nearly complete. The gap would be an explicit differentiation from the closely related siblings get_principles and get_brand_system, which the description leaves implied rather than stated.

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

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

The schema already covers 100% of parameters, but the description makes the topic parameter more meaningful by breaking it into concrete subtopics (clear space, min sizes, variants, palette, contrast, trend vs signature, etc.). This gives an agent higher confidence when choosing a filter value, which goes beyond the schema's generic 'filter by topic' statement.

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

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

The description states a clear verb+resource: 'Get brand and visual-design principles' and then enumerates specific domains (logo usage, gradient usage, imagery, visual hierarchy, brand-as-system thinking). This immediately distinguishes it from sibling tools like get_principles or get_brand_system without requiring the schema.

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

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

The description includes an explicit 'Use when the user asks about...' sentence that lists concrete triggers (branding, logos, gradients, imagery, visual consistency). However, it does not explicitly name alternatives or mention when not to use this tool, e.g., how it differs from get_principles or get_brand_system.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: matching is limited to 12 known design systems and returns the closest match with ready-to-use CSS. This sets realistic expectations about approximate matching, which is useful beyond the annotations.

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

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

The description is compact, front-loaded, and every sentence earns its place: purpose, trigger example, and output expectations. It contains no filler or redundant explanation.

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

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

There is no output schema, but the description explicitly names what the tool returns: full token set, style guide, implementation instructions, and ready-to-use CSS. It could add more on fallback behavior when no close match exists, but the core call context is covered.

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

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

The input schema provides 100% parameter coverage, including enums, defaults, and examples. The description adds little beyond restating that CSS output is possible and showing a company example, so the schema carries the main semantic load.

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

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

The description states a specific verb and resource: get a complete design system built around a specific company's branding, with a concrete example (Spotify). It clearly differentiates itself from generic siblings like get_design_system and list_design_systems by emphasizing company-matching branding.

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

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

The description gives a clear trigger phrase ('Say "Make me an app with branding like Spotify"') and describes what the tool returns. However, it does not explicitly explain when to prefer this tool over alternatives like get_design_system or what to do if the requested company is not among the 12 known systems.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description needed less safety disclosure. It adds useful behavioral context by noting each trend is time-stamped, includes fit/fail assessments, and should not be treated as a prescriptive directive — all beyond what the annotations convey.

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

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

Two focused sentences deliver the core purpose up front, followed by concrete trend examples and an important usage caveat. Every sentence earns its place, with no redundant filler or restatement of the tool name.

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

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

For a zero-parameter, read-only informational tool, the description is complete. It explains what the trend data contains, gives representative examples, clarifies that trends are time-stamped, and tells the agent how to interpret the results — including the calibration caveat.

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

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

The tool has zero parameters and 100% schema coverage, so there is no parameter ambiguity requiring explanation. The description still enriches the input semantics by indicating that the tool is self-contained and returns a curated trend set rather than needing filters or configuration.

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

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

The description states a specific verb ('Get') and resource ('current brand and visual-design trends') and goes further by listing concrete examples like bento grids, monospace type, and generative patterns. The 'current/2026/time-stamped' framing distinguishes it from static brand reference tools such as get_brand_system or get_brand_principles.

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

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

The description clearly communicates the intended use — checking current trend fit and calibration — and adds a strong usage caution: 'treat as a calibration signal, not a prescription.' It does not explicitly name sibling alternatives or exclusions, but the context is specific enough for an agent to select it appropriately.

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

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

The annotations already convey read-only, idempotent, non-destructive, and open-world behavior, so the description doesn't need to repeat them. It adds no extra behavioral context such as whether the output is static knowledge, generated content, or a generalized strategy, which leaves some ambiguity for a no-output-schema tool.

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

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

The description is compact and front-loaded with the main verb and resource, followed by a concise list of covered strategy areas. Every sentence earns its place without unnecessary filler.

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

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

For a simple two-parameter read-only lookup tool, the description plus schema is mostly sufficient: the primary type and optional stage are clear, and annotations cover safety. It still lacks explicit sibling differentiation and output-shape expectations, but the overall context is enough for an agent to make a reasonable call.

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

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

Schema description coverage is 100%, and the description largely restates the type options already present in the schema. The stage parameter and its contextual filtering are already described in the schema, so the description adds little parameterization value beyond reinforcing the topic list.

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

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

The description clearly uses 'get' as the verb and defines the resource as business and monetization strategies for digital products, with a concrete list of covered topics. It is distinct from the majority of audit/design sibling tools, though it does not explicitly differentiate itself from semantically related siblings like get_metrics_framework.

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

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

There is no explicit guidance on when to choose this tool over alternatives, and no mention of when not to use it. The description implies context through the listed topics, but the agent is left to infer when this tool is the right one among many similar knowledge-retrieval tools.

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

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

Annotations already convey readOnly, idempotent, non-destructive behavior, so the description wasn't required to repeat them. It adds that the result is a list of yes/no verification items, which is useful, but does not clarify whether the checklist is a static, pre-defined list vs. generated from the current design state.

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

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

Two short sentences that front-load the tool's purpose, resource, and output shape. Every word earns its place with no repetition of annotation or schema content.

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

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

For a simple read-only lookup tool with full schema coverage and supporting annotations, the description gives an agent everything it needs to call the tool correctly: what type to provide, why optional platform context matters (via schema), and what to expect back.

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

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

The schema already describes all parameters: 'type' has clear examples and 'platform' has an enum plus platform-specific guidance. The description adds no new parameter semantics, so this sits at the schema-coverage baseline.

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

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

States a specific verb and resource: 'Get a pre-publish checklist for a specific UI type' and clarifies what the caller receives ('actionable yes/no items to verify before shipping'). This distinguishes it from sibling audit and evaluation tools, which analyze existing pages rather than return a type-driven checklist.

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

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

The description implies this is the right tool when you need a pre-shipping checklist for a known UI type, but it never explicitly contrasts it with sibling tools like audit_page, evaluate_design, or get_page_template. There is no 'when not to use' guidance, so the agent must infer the boundary.

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

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

Annotations already establish that this operation is read-only, idempotent, and non-destructive, so the description only needs to add value beyond safety. It does by describing the return content (do's and don'ts examples, evidence, checklist), which is particularly helpful because there is no output schema. No hidden behaviors, side effects, or constraints are missing.

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

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

The description is two sentences long with no filler and front-loads the key noun phrase. It includes only the essential facts: what patterns are available and what the response contains. Every sentence contributes useful context.

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

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

For a one-parameter, read-only tool with no output schema, this description is complete. It gives the agent the full scope of the parameter, describes the result contents, and relies on annotations to communicate the safe, idempotent nature of the call. There is little missing information that would prevent a correct invocation.

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

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

The input schema already fully covers the parameter, so the baseline is 3. The description adds value by framing the type as copy recipes and listing the four domain categories in natural language, helping an agent reason about what value to pass beyond the raw enum labels. It doesn't repeat schema list verbatim, but it does make the parameter's meaning and expected content clearer.

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

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

The description uses a specific verb ('Get') and a specific resource type ('content pattern'), and details the exact copy recipe categories covered (error messages, empty-state, notifications, form validation). It also clarifies what the returned content includes, separating it from more general tools like get_principles or get_pattern. This is enough for an agent to know what this tool is for.

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

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

The description clearly indicates when to use the tool: when the agent needs copy recipes for these specific UI content categories. It gives a strong use context, but it does not explicitly mention alternatives or exclusions relative to sibling tools like get_content_principles, which keeps it just below an explicit 5.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false). The description adds value by indicating what content the tool returns and how filtering works, but it does not disclose return shape, pagination, or any other runtime behavior. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence that names the resource, gives concrete content previews, and describes the optional filter. Every part earns its place with no redundant language.

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

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

For a simple read-only tool with two optional parameters and no output schema, the description gives enough context about content and filtering. It is slightly generic with 'and more', and it doesn't mention how 'format' changes the output, but the schema fills that gap. Overall complete but not maximally thorough.

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

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

Schema description coverage is 100%, so the input schema already documents both 'format' and 'context'. The description reinforces the contextual filter with additional examples like 'form labels', but the schema already carries most of the parameter meaning, so the value added is slight.

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

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

The description clearly names the verb ('get'), the resource ('UX-writing principles'), and enumerates the actual content areas ('clarity over cleverness, active voice, error-message anatomy, inclusive language, voice vs tone'). This makes it easy to distinguish from generic sibling tools like get_principles or get_content_system.

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

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

The description implies use for UX-writing guidance and explains how to filter by context, but it does not explicitly say when to choose this over siblings such as get_principles, get_content_pattern, or get_content_system. There is clear context but no exclusions or alternative routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful context about the content categories returned, but does not disclose return shape, whether the full object is returned by default, or what happens when the section parameter is used; these are partially covered by the schema.

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

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

The description is a single focused sentence that front-loads the tool's primary purpose and then efficiently enumerates the content categories. There is no filler or repetition, and every clause adds relevant information.

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

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

For a simple read-only resource fetch, the description plus the annotated schema provide enough context to use the tool correctly. It might be slightly stronger with an explicit note that all sections are returned when no section is specified, but the section parameter's 'Default: all' already carries that information.

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

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

Schema description coverage is 100%, with the id and section parameters already well documented, including the section enum and default. The description adds no significant extra parameter semantics beyond already enumerated by the schema.

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

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

The description clearly names the resource being fetched: a brand's content design system, and goes beyond that by listing the exact components included (voice, tone shifts, vocabulary, grammar, content patterns, inclusive language). It does not explicitly differentiate from sibling tools like get_design_system, get_content_pattern, or get_content_principles, but the target is clear and specific.

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

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

The description implies when this tool should be used — when a caller needs content voice, vocabulary, grammar, or content-pattern guidance for a brand. However, it gives no explicit guidance about when not to use it or how it relates to siblings such as get_content_pattern or get_design_system.

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

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

The annotations already communicate readOnlyHint=true and idempotentHint=true, so the description does not need to restate safe read behavior. It adds valuable detail by listing the actual content returned, going beyond what the annotations convey.

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

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

The description is one compact sentence, front-loaded with the action and resource. It lists the return contents efficiently and includes a purposeful application phrase without filler.

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

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

For a simple read-only getter with one optional parameter and no output schema, the description adequately conveys what the tool returns and its intended context. It does not describe how the stage parameter changes the returned templates, but the schema enum and default value largely fill that gap.

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

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

The schema fully documents the single parameter with an enum and a clear description, so the schema carries most of the load (coverage is 100%). The description does not add parameter-level semantics, but it does provide useful context about the template contents that complements the stage enum.

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

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

The description clearly states the operation ('Get the D4D framework templates') and identifies the exact resource and contents it returns: customer problem statement, ideal state, hypothesis, LOFA, and experiment templates. This makes the resource unambiguous and helps distinguish it from other getter tools in the sibling list.

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

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

The phrase 'for structured product thinking' implies when this tool is appropriate, but it does not specify when to use it instead of similar knowledge resources such as get_principles, get_checklist, or get_research_method. No explicit alternatives or exclusions are provided.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needs to add behavior beyond that. It adds the default return shape (token categories and DTCG/CSS/flat formats), which is useful in the absence of an output schema, but it says nothing about behavior for unknown IDs, missing token groups, or the size of an unfiltered response.

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

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

A single front-loaded sentence with zero filler: the purpose is stated first, then all supporting detail is compressed into one clause. The token-category enumeration is slightly redundant with the group parameter schema, so it is not perfectly minimal, but every remaining word carries usable information.

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

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

For a simple read tool this is broadly sufficient: the schema documents all three parameters fully and annotations cover side-effects, while the description signals the default response shape (token groups and formats) despite there being no output schema. Notable gaps are the lack of guidance on discovering a design system ID, confirmation that all groups are returned by default, and any edge-case behavior for invalid IDs.

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

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

Schema description coverage is 100%, so the baseline is 3: every parameter, including the format enum with defaults, is already documented in the schema. The description mostly restates those same values with slightly richer labeling ('W3C DTCG, CSS custom properties, or flat'), adding meaning but not compensating for any coverage gap.

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

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

The description opens with a specific verb-resource pairing: 'Get design tokens for a specific design system', and enumerates the token categories and output formats. 'Specific' plus 'design tokens' clearly distinguishes it from list_design_systems, get_brand_system, and list_design_system_components, though it does not name any sibling explicitly.

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

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

Usage is only implied: the token categories and formats suggest this is for retrieving design token values for a chosen system. However, there are no explicit conditions, exclusions, or alternatives given — for instance, no pointer to list_design_systems for discovering valid IDs or to get_brand_system for non-token brand data — leaving routing decisions entirely to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds return-content transparency by stating it returns structure, when-to-use info, pitfalls, and examples, which is useful beyond the annotations.

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

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

Two sentences, front-loaded with the resource list and followed by return contents and usage triggers. No filler or repeated schema information.

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

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

The tool has 2 optional params fully documented in the schema, no output schema, and annotations covering side effects. The description adds return-value expectations and triggering phrases, making it complete enough for reliable invocation.

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

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

Schema description coverage is 100% — both parameters ('id' and 'search') are already documented in the schema. The description adds no meaningful parameter semantics beyond the framework list, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Get') and names a distinct resource class ('product-metrics framework') with an explicit list of six frameworks. It is immediately distinguishable from sibling knowledge-retrieval tools by its metric/measurement focus.

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

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

Provides an explicit trigger condition: use when the user asks 'how should we measure success?' or 'what metrics should we track?'. It does not name when-not-to-use or point to alternatives, but the quoted use cases are clear enough for an agent.

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

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

Annotations already cover the read-only, idempotent, non-destructive safety profile, so the bar for behavior disclosure is lower. The description adds useful output-shape context by stating the returned components (do's, don'ts, evidence, checklists), which matters because there is no output schema. It does not disclose more behavioral detail such as behavior on invalid or unsupported type values.

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

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

The description is single focused sentence with the main verb-object relationship front-loaded. The long list of pattern types is somewhat heavy, but each listed item is informative and supports correct parameter selection. No filler or redundant restatement of the tool name, though the sentence is a bit list-heavy.

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

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

Given the absence of an output schema, the description usefully states what the return content includes and lists supported pattern domains. The annotations handle safety/idempotence, and the schema handles parameter semantics. A minor gap is lack of explicit discrimination from the several similar get_* sibling tools, especially get_principles and get_checklist.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description's enumerated pattern categories overlap with the type parameter's examples but do not add exact syntax, normalization rules, or behavior of the goal/platform filters beyond the schema. This meets the baseline but adds little extra semantic value.

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

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

The description clearly identifies the action ('get'), the resource ('UI/UX patterns'), and what is returned ('do's, don'ts, evidence, and checklists'). It names specific pattern types, making the tool's scope fairly concrete. It does not explicitly differentiate itself from siblings like get_principles, get_checklist, or get_content_pattern, but the combination of 'patterns' and the enumerated design types makes the core purpose unambiguous.

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

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

The description says what the tool returns but gives no guidance on when to prefer it over similar siblings such as get_principles, get_checklist, or get_content_pattern. There is no stated when-to-use/when-not-to-use context, no exclusions, and no alternatives named.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context by detailing the content delivered and noting results are 'matched to' the design context, suggesting selection/filtering behavior.

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

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

The description is a single tight sentence that front-loads the purpose before enumerating the returned principle types. Every phrase earns its place: no filler, no repetition, and no redundant restatement of the tool's name.

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

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

The description, combined with a fully-documented schema and safe-read annotations, gives an agent enough to select and invoke the tool. It lacks an explicit statement about the platform/category substitutions, but those are fully captured in the schema descriptions, so this is not a material gap.

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

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

Schema description coverage is 100%, so descriptions already define context, format, category, and platform adequately. The description's first sentence reinforces the 'context' parameter concept but does not need to add more; baseline 3 is appropriate given high coverage.

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

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

The description names a specific verb and resource: 'Get design principles' for a UI context, and enumerates the types of content returned (heuristics, UX laws, Gestalt, accessibility, typography, color). This distinguishes it from sibling tools like get_content_principles or get_brand_principles, whose scopes differ.

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

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

The description clearly establishes when to use the tool: for a UI context, matched against what you're designing. It does not explicitly name sibling alternatives or state exclusions (e.g., when to use audit_* or evaluate_design instead), which keeps it at a 4 rather than a 5.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint). The description adds useful behavioral context beyond those annotations by explaining the return payload: protocols, guidance, evidence, and a checklist. It does not discuss edge cases like empty search results or content availability for obscure methods, but for a read-only lookup tool this is not a significant gap.

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

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

The description is dense but well-organized: the first sentence establishes purpose and enumerates the full category map, the second defines the return structure, and the third gives the use case. No sentence is filler or redundant with the schema annotations.

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

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

There is no output schema, so the description compensates by specifying exactly what the tool returns ('protocols, do/don't guidance, evidence... checklist'). It also covers parameter categories, use cases, and the safe read-only nature of the call. An agent has enough information to call this tool correctly in the intended contexts.

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

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

The schema covers both parameters at 100% with meaningful descriptions, including the category enum and the default value. The description broadly repeats the category families ('qualitative', 'quantitative', 'usability') but adds no parameter-level depth beyond the schema. Baseline 3 is appropriate because the schema carries most of the parameter-semantic weight.

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

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

The description uses a specific verb with a specific resource: 'Get research method details — qualitative... quantitative... or usability...' It also enumerates what is returned ('protocols, do/don't guidance, evidence, and a checklist'), which clearly distinguishes it from sibling knowledge-retrieval tools like get_principles or get_checklist. The explicit category breakdown leaves no ambiguity about the tool's scope.

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

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

The description closes with a clear when-to-use instruction: 'Use when the user is designing a study or asking how to measure something.' It provides a solid usage context without explicitly naming alternative tools or exclusions, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral detail by stating the tool 'returns patterns, do/don't guidance, evidence, and a checklist,' making the response format predictable for the agent.

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

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

The description is two sentences long with no filler. It front-loads the core action and resource, then immediately lists return contents and when to use the tool. Every sentence earns its place.

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

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

Given a one-parameter enum schema, readOnly/idempotent annotations, no nested objects, and no output schema, the description is complete. An agent can select this tool, choose the correct enum value, and invoke it with confidence based on the information provided.

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

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

The schema already covers the single parameter `type` at 100% with a full enum and description. The prose mostly restates those enum values, though it adds 'recovery' as an alias for the moments-of-truth context. This is useful but does not substantially extend schema-provided meaning.

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

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

The description clearly identifies the action ('Get'), the resource ('a service design pattern'), and enumerates the specific pattern types. It is clearly scoped to service design and therefore distinct from the generic sibling get_pattern, though it does not explicitly contrast itself with close siblings like get_service_standard or get_checklist.

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

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

The description provides clear trigger conditions: 'Use when the user is designing a service flow, escalation, cross-channel experience, or moment of truth.' It does not, however, say when not to use this tool or name alternatives for non-service design requests, so it lacks explicit exclusions or sibling routing.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful context beyond annotations: the exact content scope (14 points), its government origin, and its broader applicability as a service-quality checklist.

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

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

Three sentences with no filler: the resource, its contents, and the intended use case are all front-loaded and purposeful. Every sentence earns its place.

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

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

For a parameterless retrieval tool, the description fully covers what the service standard is, how many points it has, why it matters, and when to invoke the tool. No additional context is needed.

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

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

The tool has zero parameters and 100% schema coverage, so there is nothing for the description to explain. It meets the baseline for parameterless tools.

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

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

The description names a specific verb and resource — getting the GOV.UK Service Standard — and specifies exactly what it contains: 14 points for evaluating service readiness. This clearly distinguishes it from generic siblings like get_checklist or get_principles.

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

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

The description gives an explicit trigger: 'Use when the user asks how to evaluate a whole service.' It does not enumerate exclusions or alternative tools, but the invocation context is clear and actionable.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so much of the behavioral burden is covered. The description adds that this is specifically about brand voice systems, which adds context, but it does not disclose return shape, pagination, or any limitations. With read-only annotations in place, the added behavior context is moderate rather than rich.

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

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

A single, front-loaded sentence states what the tool offers and immediately grounds it with examples. Every word earns its place on, and no unnecessary context is included.

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

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

For a simple read-only list with two optional params and a schema documenting both, the description communicates the core purpose and scope effectively. It does not mention return fields or how this differs from sibling listing tools, but those are not essentials for an agent to understand what the tool invokes.

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

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

The input schema already describes both parameters, with the search parameter covering name, description, or tag and the category parameter listing all allowed categories. The description merely paraphrases 'filter by category or search by name' and actually under-specifies search scope, so it adds almost no value beyond what the schema provides.

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

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

The description clearly states the verb ('Browse') and resource ('content design systems'), and explains they are brand voice and tone guides with concrete examples. It does not explicitly contrast itself with siblings like list_design_systems, but the examples make the focus reasonably distinct.

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

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

The description explains how to filter, not when to use this tool versus alternatives. It gives no cues for choosing list_content_systems over sibling list_design_systems or get_content_system, so an agent must infer the appropriate context from the tool name and examples.

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

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

The annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds that entries include typical inputs and best-for guidance, which is useful output-context, but it does not disclose anything beyond that: no auth expectations, no rate-limit behavior, no pagination/syncing behavior, and no data consistency caveats. Given the existing annotations, a 3 is reasonable.

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

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

The description is a tightly packed, three-sentence structure with the verb and resource first, then scope, then the useful output shape. Every sentence adds new information, there's no filler, and it reads naturally for an agent scanning tool descriptions.

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

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

Given a simple tool with two optional, 100%-documented parameters and no nested objects, the context is mostly complete for listed use. The description hints at return value details by saying 'each entry lists typical inputs and best-for guidance,' which largely compensates for the absence of an output schema. The final remaining gap is lack of a more explicit pointer to sibling listing tools for different contexts (e.g., list_creative_presets), so a knowledgeable agent can select the best alternative.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's references to image, video, 3D, audio, and analysis align conceptually with the media_type enum, but do not meaningfully extend the schema's per-parameter meaning. The description frames the tool as browsing catalog entries and does not add explanatory detail about the capability parameter's set of accepted values beyond what the enum and examples already provide.

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

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

The description uses a specific verb ('Browse') and names a distinct resource: Raven's provider-agnostic creative model catalog. It also scopes the catalog to capability slots for image, video, 3D, audio, character consistency, and creative analysis, which clearly differentiates this from sibling list tools like list_creative_presets or list_generation_jobs.

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

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

The description conveys clear context: this is for surveying creative model capability slots and each entry provides typical inputs and best-for guidance. However, it gives no explicit 'when to use this vs. alternatives' signals, such as 'use list_creative_presets when you need ready-made presets' or examples where this tool is not appropriate. Usage is strongly implied by the catalog framing but never made explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is well covered. The description's verb 'Browse' aligns with those annotations and does not contradict anything. Although no deeper behavior like sorting or response limits is disclosed, the annotations reduce the need for additional behavioral context.

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

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

The description is a single sentence that front-loads the action and object before enumerating categories. The category list is long but relevant to the browse use case, and there is no redundant filler.

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

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

For a simple read-only listing tool with full schema coverage, the description supplies the domain and purpose without demanding an output-schema explanation. It is not exhaustive (e.g., no pagination or response structure), but those omissions are minor given the low complexity and available annotations.

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

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

Schema coverage is 100% for both parameters (search and media_type), so the baseline is 3. The description does not discuss either parameter directly; its category list does not map to the media_type enum. It neither harms nor extends parameter understanding beyond the schema.

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

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

The description explicitly states a verb ('Browse') and a resource ('Raven creative presets'), and it enriches the purpose by listing the categories of presets (product photoshoots, marketplace cards, UGC ads, etc.). It distinguishes itself from adjacent list_* tools through the preset domain, though it does not explicitly call out a sibling alternative, so a 4 rather than 5.

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

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

No when, when-not, or alternative tool guidance is provided. The description does not tell the agent when to use list_creative_presets versus list_creative_models, list_templates, or other listing tools. The use case is only implied by the noun list.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive, which covers the safety profile. The description adds meaningful behavior: it returns a browsable list of available systems, applies optional filters, and treats 'user' as a category for saved personal systems. It does not mention pagination or ordering, but for a listing tool the annotations plus filter semantics are strong.

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

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

Two sentences with no filler. The first sentence states core purpose, the second enumerates valid filter values. It is front-loaded and every clause adds information.

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

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

This is a simple read-only list tool with fully documented optional parameters, an idempotent/read-only annotation, and no output schema. The description is complete for deciding whether and how to invoke it. Slightly more context about what fields each returned item contains would push this to a 5, but it is not necessary for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters fully. The description repeats the category filter set and adds the 'search' semantics, providing marginal value over the schema without needing to compensate.

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

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

The description names a specific verb ('list'), a resource ('design systems'), and the available filters ('category' and 'search'). It clearly distinguishes itself from the related sibling 'get_design_system' (singular fetch vs. plural browse) and 'list_design_system_components' (a different resource).

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

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

The description makes the core use case explicit—browsing available design systems before selecting one—and spells out the two supported filtering modes. It does not explicitly state when one should use get_design_system or list_design_system_components instead, but the intent to enumerate available systems is unambiguous.

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

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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds no additional behavioral details beyond the search scope, such as how results are ranked or returned. Given the annotation coverage, this is acceptable but not especially informative.

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

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

The description is two short sentences, front-loading the core function in the first sentence and giving usage guidance in the second. No filler or redundancy, and every clause contributes to helping the agent decide when to use this tool.

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

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

For a read-only search tool with two simple parameters and full schema descriptions, the description is nearly complete. It explains scope and usage context but stops short of describing output shape or how to interpret results, which an output schema would normally handle. Given no output schema exists, a small gap remains, but the tool is simple enough that this is not a serious risk.

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

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

Schema description coverage is 100%, so parameters are already fully documented with examples. The description reinforces the meaning of the `layer` enum by naming the categories (principles, patterns, business) that match the enum values. It does not contradict the schema and adds slight contextual meaning without needing to compensate for gaps.

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

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

The description specifies the exact action ('Search') and the full resource scope ('all design principles, UI patterns, and business strategies'), distinguishing it from category-specific siblings like get_principles or get_pattern. The phrase 'or don't know which category to look in' helps an agent understand this is the cross-cutting discovery tool, not a targeted one.

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

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

The description gives an explicit when-to-use signal: use it when you need specific guidance or are unsure of the category. It implies the alternative is using category-specific getter tools when the category is known, though it does not name them directly. This is clear context but not a fully explicit when-not-to-use statement.

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

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

The aliases already declare readOnly, idempotent, and non-destructive; the description adds meaningful context with 'Pure offline math.' It also discloses exactly what is computed and returned: smallest foreground adjustment, an alternative background adjustment, and the achieved ratio and direction.

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

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

The description is front-loaded with the core purpose and avoids verbose fluff. There is some redundancy between 'Given failing WCAG color pairs' and 'audit_contrast's failing pairs,' but each sentence still contributes useful operational context.

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

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

With no output schema, the description is sufficiently explicit about what the tool returns: the minimal color change, the achieved ratio, and direction. It also clarifies it's offline, which helps set expectations. An exact response shape is not described, but enough information exists to call it correctly.

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

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

The input schema covers all properties at 100%, including the 'level' scale and targetRatio override semantics, so the description doesn't need to re-document them. It adds the helpful note that pairs should come from audit_contrast's failing-pair output, but that is more usage context than parameter-level semantics.

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

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

The description specifies a concrete verb and resource: it computes the MINIMAL color change for failing WCAG color pairs. It also distinguishes itself from audit_contrast by stating that it consumes that audit's failing pairs rather than performing the audit.

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

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

The description explicitly says to feed it audit_contrast's failing pairs to get concrete passing values, which is clear when-to-use guidance. It frames the tool as the fast path instead of brute-forcing colors, though it does not spell out explicit exclusion cases.

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