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

The annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context on top: it auto-detects the surface, fans out to the appropriate audit set, and accepts a project for taste binding. It does not discuss every possible caveat, but it does not hide any significant side effect either.

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

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

The description is compact and front-loaded: it begins with the purpose, then explains the detection/fan-out behavior, then gives the actionable warning to prefer this over granular audit tools. There is no filler or redundant restatement of the schema.

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

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

For a wide-dispatch tool with no required parameters, the description is strong because it defines the accepted target types and the relevant check families. However, it doesn't explicitly state that at least one target input should be provided, which matters since all 10 parameters are optional. The wealth of the schema mostly compensates.

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

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

Schema description coverage is 100%, so the parameters are already self-documenting. The description contributes general context like 'target' and 'project' taste binding, but most of that meaning is already expressed in the schema. It adds little about parameter formats, precedence, or combinations beyond what the schema communicates.

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

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

The description states a specific action — 'Run all applicable Raven audits for a target' — and explains the scope with a concrete verb and resource. It also distinguishes the tool from its siblings by explicitly telling agents not to pick individual audit_* tools. This makes the tool's role as an umbrella dispatcher unmistakable.

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

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

The description gives direct usage guidance: use this instead of choosing individual audit_* tools. It also explains how the surface is detected and which check families run per surface, so an agent knows this is the right entry point for broad audits rather than for a single focused check.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive hints. The description adds behavioral transparency about live adversarial queries and the specific verdict categories returned, which are not inferable from annotations alone. There is no contradiction.

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

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

The description is two tight sentences with front-loaded action and no filler. Every sentence earns its place: the first explains the operation and output, the second clarifies the key value proposition.

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

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

The description captures the high-level purpose and output verdicts, but the tool has complex nested parameters and no output schema. It does not fully describe how query expectations should be expressed or how the expected_shape_schema should be structured, though much can be inferred from the schema itself.

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

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

Schema description coverage is 0%, and the description does little to explain the three required parameters beyond mentioning an expected shape schema and per-query expectations. Property names like endpoint_url, queries, and expected_shape_schema are somewhat self-explanatory, but the description fails to enrich their meaning or explain nested expectation fields.

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

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

The description states a specific verb and resource: it runs adversarial queries against a live endpoint and returns per-query verdicts. It clearly conveys the tool's unique purpose of catching shape-valid but wrong responses, but it does not explicitly distinguish itself from sibling tools like audit_contract.

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

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

The description implies when to use the tool: when a live API's responses need adversarial validation against both a shape schema and per-query expectations. It does not provide explicit exclusion criteria or alternatives, so the guidance is implied rather than explicit.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it measures per-pixel luminance variance in the bottom strip and interprets uniform background as clean versus high-variance UI content as likely-sliced. This informs the agent about the mechanism and expected signal beyond the annotation flags.

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

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

The description is well structured and front-loaded with the core detection purpose, then adds an example, method, and expected signal validity. Every sentence earns its place: no tautology, no repeated schema content, no filler, and the epsilon are kept at a useful detail level.

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

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

For a read-only, single-parameter audit tool, the description covers purpose, input, method, and result interpretation. The only gap is the lack of an explicit description of the return value shape, especially because there is no output schema; an agent would still need to infer whether the tool returns a pass/fail, a list of offenders, or report details.

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

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

Schema coverage is 100% because image_paths already has a clear description: 'Filesystem paths to PNG files to check for sliced/cut-off bottom content.' The tool description mostly restates this same idea, so it adds little parameter information beyond what the schema already provides.

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

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

The description leads with a specific verb and resource: 'Detect PNG exports whose content is sliced/cut off at the bottom edge.' It goes beyond the generic audit_* sibling pattern by naming the exact failure mode, giving an example (mid-form Figma export), and describing the per-pixel luminance method. This clearly distinguishes it from other audit tools.

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

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

The description provides clear context: use this when checking PNG files for bottom-edge slicing, especially cases where dimension/ratio checks would not catch the problem. It implicitly frames the alternative ('Dimension/ratio checks cannot catch cut content'), but does not explicitly name a sibling tool or state a hard when-not-to-use condition, so it stops short of a full 5.

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

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to re-assert non-mutation. It adds valuable behavior beyond the annotations by stating that it flags contracting and always returns a BLOCK/PASS verdict.

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

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

Two sentences front-load the action and scope, describe the contract shape, enumerate the bug classes, and state the verdict output. No word is wasted and no structured field is redundantly repeated.

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

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

For a tool with no output schema, the description gives adequate context: inputs, purpose, anomalous cases, and the BLOCK/PASS verdict. The main gap is mode-specific behavior for contract_spec, such as the difference between tokens mode and envelope mode, but the tool remains invokable as described.

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

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

With 0% schema description coverage, the description partially compensates by explaining that contract_spec represents token list/field set/schemaVersion and file_paths represents the N source files. However, it does not explain the mode enum tokens/envelope, the meaning and usage of schemaVersionPattern, or whether file_paths expects literal paths, globs, or directories.

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

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

The description names a concrete verb and resource: "Verify a wire contract ... is identical across N independent source files", lists the input families (token list / field set / schemaVersion), and enumerates the specific issue classes it detects. This clearly differentiates it from nearby audit tools like audit_api_contract, audit_parity, or audit_consistency.

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

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

The intended use case is clear: cross-language wire contract consistency among iOS Swift, proxy JS, and Android Kotlin source files. It lacks an explicit when-not-to-use statement or named alternatives, so it does not hit a 5, but the context is still concrete enough for an agent to decide when to select it.

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

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?

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value beyond annotations by revealing the no-args DevTools-snippet behavior and by explaining what each invocation actually analyzes.

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

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

The description is well structured with numbered check categories and a front-loaded purpose statement. It is a little long, but the length is justified by having three distinct modes with different inputs.

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

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

With zero required parameters and three optional modes, the description thoroughly explains when and how to call the tool. The only real gap is that there is no output schema and the description does not state the expected result format beyond saying content is 'flagged'.

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

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

The schema covers all parameters well, but the description adds operational meaning: `frames` is for aspect-ratio/crop geometry, `clips` for baked-in pan/zoom, and `edge_frames` for truncated content. This directly helps an agent decide which optional argument to supply.

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

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

The description opens with a clear verb and resource: 'Detect cropped content in device-mockup frames' and then enumerates three precise checks (GEOMETRY, MOTION, EDGE). This makes it easy to distinguish from generic page/video audit siblings.

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

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

It gives explicit usage modes: pass `frames` for geometry, `clips` for motion/Ken Burns, `edge_frames` for truncation, and no args to get a DevTools snippet. It does not explicitly state when to prefer an alternative tool for non-device-frame audit cases.

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

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/destructive annotations, the description reveals what the audit will score (44×44pt targets, contrast, visual rhythm), that iOS semantic colors like secondaryLabel/tertiaryLabel are treated as platform-standard with warn-not-fail behavior, and that screenshot is optional. This materially clarifies behavior.

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

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

The description is compact, front-loaded with the core purpose, and every sentence carries distinct value: purpose, alias relationship, no-args usage, example payload structure, scoring criteria, and return shape reference. No redundant filler.

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

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

For a read-only analysis tool with rich schema coverage and annotations, the description fully covers what inputs are needed, how to invoke it, what scoring dimensions are inspected, and what return shape to expect. The no-arguments behavior and alias note make it safe for an agent to use without additional research.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage semantics by showing an expected elements payload and viewport shape, and clarifying that the screenshot is optional. It also gives key scoring semantics such as point-based dimensions and warn-not-fail color handling.

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

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

The description clearly states the tool audits a rendered iOS screen from a view-hierarchy/accessibility snapshot, and explicitly identifies it as an alias of audit_screen with platform 'ios'. This distinguishes it from broad siblings like audit_page and audit_screen while also signaling the return shape.

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

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

The description gives clear usage context: call with no arguments to see the expected snapshot shape, or call with elements and viewport to perform scoring. It also names the alias relationship and the same return shape as audit_page. It does not explicitly call out alternatives or exclusions, but the iOS scope provides adequate guidance.

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

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?

The description does add behavioral context: it returns pass/fail per check with fix instructions, and it explains how containerMaxWidth changes the max-width check from a generic 1200px heuristic to a token-aware divergence check. However, annotations state readOnlyHint=false, idempotentHint=false, and destructiveHint=true, while the description's 'audit' language implies a non-mutating analysis and never discusses side effects that would justify the destructive mismatch. This is a nontrivial gap, but not a direct contradiction.

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

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

The description is dense but appropriately so for a tool with 9 parameters and five audit categories. Every clause earns its place, and the purpose and the main parameter special-case are front-loaded. It is a single long sentence rather than a scannable structure with bullets or paragraph breaks, so slightly less structured than ideal.

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

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

The description gives a decent overview of what the audit covers and roughly what it returns, but there is no output schema and the return-value description is incomplete—it does not mention score, grade, screenshots, passes list, or fix_priority, though some of this is inferable from the compact parameter description. It also does not state whether at least one of url or html is needed and does not address the many sibling audit tools that might be the better choice.

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

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

Schema coverage is high (89%) and the schema already describes each parameter, so the baseline is 3. The description nonetheless adds semantic value for containerMaxWidth by explaining how it affects the heuristic, what 'token-aware' means, and the fact that it flags containers that are either too narrow or too wide. This goes beyond the schema's basic description.

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

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

The description opens with a clear verb and resource: 'Audit HTML/CSS against Raven's design quality standards,' then enumerates several concrete check domains, so an agent can easily recognize this is a broad page-level design audit rather than a single-issue audit. However, it never explicitly contrasts itself with the many specialized audit_* siblings (e.g., audit_typography, audit_contrast, audit_url), so it is clear but not fully differentiated.

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

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

The description does not say when to prefer this tool over an audit_* sibling or when not to use it. There is no alternative route or exclusionary context. The only conditional usage advice is about the optional containerMaxWidth parameter, which is parameter guidance, not tool-selection guidance.

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

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?

Beyond the already-declared read-only and idempotent annotations, the description discloses exactly what the audit flags and rewards, including dark-mode handling being conditional on multi-mode apps. This gives an agent a reliable model of the tool's behavior.

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

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

The description is dense but efficient: purpose first, then check list, then boundaries, then return expectation. Every sentence earns its place, and the longest sentence is a useful enumeration rather than filler.

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

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

With rich parameter schema, annotations covering safety, and no output schema, the description still ties the return behavior to an existing shape: 'Same return shape as audit_page.' It also gives enough audit-criterion detail and boundary context for real selection and invocation.

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

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

The schema description coverage is 100%, so each of the 5 parameters already documents its meaning, defaults, and effects. The main description doesn't repeat or deeply expand individual parameter semantics, so the baseline of 3 applies.

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

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

The description names a specific verb and resource: 'Audit React Native / Expo source against iOS HIG + Android Material conventions' and immediately lists concrete checks like missing accessibilityLabel, insufficient hitSlop, and allowFontScaling. It also clearly differentiates itself with 'RN-native checks only — no web/CSS or SwiftUI rules.'

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

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

It gives a clear scope boundary ('RN-native checks only') and an explicit way out for rendered screens: 'RN renders to native widgets, so audit_ios_screen scores the rendered screen.' It does not fully spell out alternatives for CSS/SwiftUI or when audit_page would be a preferred choice, but the context is easy for an agent to follow.

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

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

Annotations already declare the tool safe and read-only, so the bar is lower. The description counts credits by adding real behavior: no-arg self-documentation mode, platform-specific thresholds, and nuanced handling of Material/Android semantic colors as warnings rather than failures. It also links its return shape to audit_page.

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

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

Five short front-loaded sentences, no filler and no repetition of schema constituents. Purpose, invocation, platform semantics, scored dimensions, and return-shape reference are each given exactly one sentence.

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

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

For a 7-param tool with nested objects, no required params, and no output schema, the description is strong: it explains the input model via the no-args response and the return contract via audit_page. The only residual gap is scroll_settle and broader return-value detail, but those are partially covered by the self-documented protocol.

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

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

Schema description coverage is 86%, so the baseline is 3 with no extra param info. The description still adds value: it explains what the platform choice actually changes, and the no-arguments invocation mode is a behavior absent from the schema. It does not clarify the otherwise undocumented scroll_settle, which keeps it below a 5.

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

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

The description uses a specific verb and resource: 'Audit a rendered mobile screen (iOS or Android) from a view-hierarchy/accessibility snapshot.' It also enumerates what is checked — touch targets, contrast, and visual rhythm — so it is not confused with a single-purpose audit tool and identifies the operation precisely.

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

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

It gives direct invocation guidance: call with no arguments to receive the snapshot shape and capture instructions, pass platform:'android' to change scoring semantics, and omit platform for iOS. It does not explicitly state when NOT to use this tool in favor of alternatives like the specialized audit_tap_targets or audit_contrast, but the context is clear.

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

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

Annotations already declare the tool read-only and idempotent, so the safety profile is covered. The description adds meaningful behavioral context beyond that: specific violations that get flagged (font sizes below ~13pt, empty AccentColor, sub-44pt frames, off-grid spacing), the 'Rewards...' scoring behavior, and the output contract ('pass/fail per check with fix instructions').

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

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

A single tight paragraph that front-loads the action, packs the check list into compact parenthetical clusters, tacks on the scope restriction, and ends with the return contract. Every clause earns its place — around 70 words with zero filler, repetition, or marketing fluff.

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

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

Given the moderate complexity and no output schema, the description adequately covers the return shape ('pass/fail per check with fix instructions') and the main behavioral surface. The optional profile/project binding and strict-mode grading semantics are carried by the 100%-covered schema, so nothing critical needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, and each of the 5 parameters already has a rich description (source concatenation, strict-mode semantics, taste-surface binding, accent_color_contents verification). The tool description adds only one cross-reference — tying the accent_color_contents parameter to the empty/undefined AccentColor check — which is useful marginal context but not compensating work, so the baseline 3 applies.

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

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

The description uses a specific verb ('Audit') with a specific resource ('SwiftUI source') and a named standard ('Apple's Human Interface Guidelines'), then enumerates the exact rule categories checked. It also distinguishes itself from sibling audit tools by declaring 'iOS-native checks only — no web/CSS rules'.

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

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

The intended use context — SwiftUI iOS HIG auditing — is clear, and the exclusion 'no web/CSS rules' provides some boundary on when NOT to use it. However, none of the many overlapping audit siblings (audit_typography, audit_tap_targets, audit_contrast, audit_ios_a11y) are named, so when to choose this tool over an alternative is left to the agent's inference.

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

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint: false, but the description adds far more: not_assessed instead of guessing, rule delegation to Raven engines, silence-over-speculation policy, accepted contract corpus precedents, design-note verification as acceptance criteria, and build_hints on expensive techniques. The description and annotations align; there is no contradiction.

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

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

The definition is very long and runs as one dense paragraph, so it is not structurally graceful. However, nearly every sentence carries a distinct behavioral policy or edge case that matters, and the opening line immediately gives the core function. The density is mostly earned rather than padded.

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

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

For an 8-parameter tool with no output schema, the description is unusually complete. It covers target variants, scope resolution, project binding prerequisites, document_kind behavior, verdict semantics, finding types, fidelity_findings, note assessments, REF-* deltas, restraint findings, and build_hints. An agent has nearly everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully supplements the schemas. It explains url's rendered headless scroll-settle behavior, surface omission as warn-not-block, project binding resolution, source_text as a verbatim token diff, and document_text's artifact/portrait distinction for note fidelity. These are behavioral semantics the schema alone cannot convey.

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

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

Opens with a specific, non-tautological purpose: 'Judge a target against a taste profile'. It also names the concrete input modes (html, text, url) and the meaningful output dimensions, which separates it from the many generic audit_* siblings. The tool is clearly associated with taste profiles rather than generic page-score or checklist audits.

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

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

Gives strong selection and run-order guidance: pass url/html/text depending on target type, pass surface to control scope-tagged rules, pass project to reuse a saved surface binding, and run get_taste_interview first for a new project with no binding. It does not explicitly exclude sibling audits, so an agent still has to infer when not to use this tool in favor of, for example, audit_page or audit_content.

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

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

Annotations already establish this as read-only, idempotent, and non-destructive. The description adds behavioral context beyond those annotations by disclosing the headless-Chromium dependency for URL mode and listing the exact report shape, including findings with rule, severity, message, and fix. No contradiction with annotations.

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

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

Each sentence serves a purpose: scope, input modes, report contents, and distinction from a sibling tool. The report breakdown into (a), (b), and (c) is compact and readable without losing necessary specificity.

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

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

For a read-only audit tool with no output schema, the description is unusually complete: it names both modes, the external Chromium requirement should not return any malicious URL, and it enumerates the return fields (scale, line_height, weight_ladder, nodes_analyzed, findings). The only minor ambiguity is behavior when neither input is provided, but the 'or' wording sufficiently implies that at least one mode is expected.

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

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

The schema already documents both parameters fully, which sets a high baseline. The description adds value by framing URL and nodes as alternative modes, telling agents to pass 'a URL or a pre-collected snapshot,' which clarifies how to decide which parameter to populate.

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

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

The description opens with a specific verb and resource: 'Audit the typographic SCALE...', then enumerates exactly what it reports (modular scale, line-height consistency, weight ladder). It also explicitly distinguishes itself from audit_page's pass/fail typography checks, so an agent can select it correctly among sibling audit tools.

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

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

The description gives two clear input modes — a rendered page via URL or a pre-collected nodes snapshot — and notes that 'URL mode requires headless chromium.' It also says the tool goes beyond audit_page's pass/fail typography checks, providing useful alternative context, but it does not fully spell out when-not-to-use conditions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds valuable context beyond that: the tool navigates to and controls a LIVE external URL, fires hover/click/focus events, scroll-settles the page to trigger IntersectionObserver reveals and play videos, and requires headless chromium. It also discloses that findings are triaged into confirmed | likely-artifact | inconclusive with evidence, which shapes expectations about output quality. No contradiction with annotations.

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

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

The description is dense but front-loaded, opening with the core mechanism ('render-and-capture audit... renders a LIVE URL') and building through pipeline, checks, output tagging, use cases, and the prerequisite. Every sentence earns its place and no filler is present for a tool of this complexity; it is long, but the richness justifies it.

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

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

With no output schema, the description explains the result shape: findings with confirmed | likely-artifact | inconclusive tags, evidence, severity ranking, and per-capture data. It covers prerequisites, behavior, and use cases for a 9-parameter high-complexity tool with a live-URL dependency. The only small gap is what isn't mentioned — runtime expectations or error behavior — so nothing critical for an agent deciding to call it correctly is missing.

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

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

Schema description coverage is 100%, and every parameter (url, themes, compact, timeoutMs, viewports, interactions, scroll_settle, containerMaxWidth, includeScreenshots) already carries its own meaning and defaults. The description adds pipeline-level color (e.g., why scroll_settle matters, why interactions exist) but does not add per-parameter detail beyond the schema — so the baseline 3 is appropriate.

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

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

The description names a specific verb and resource ('render-and-capture audit' of 'a LIVE URL') and describes exactly what the tool does: scroll-settles, fires interactions, captures pixels/DOM, then runs specific rule engines. It explicitly positions itself against the alternative class — 'invisible to HTML-string/geometry audits' — and even names the complete cases it catches, which distinguishes it clearly from the many sibling audit tools.

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

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

The final sentence gives concrete when-to-use guidance ('catches real-world visual nits invisible to HTML-string/geometry audits') and lists examples: cropped images, blank videos, hover white-wash, sliced exports, hidden-on-mobile content. It also states a hard prerequisite (headless chromium). It doesn't name sibling alternatives like audit_page or audit_contrast explicitly as 'use these when...', but the exclusion direction is clear.

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

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?

It discloses a lot beyond the annotations: upsert semantics, carried-forward behavior for omitted fields and clearing for explicit empty values, live capture of references, consistency checks that produce consistency_warnings, build_hints for expensive techniques, and the enforced refusal when no calibration content results. Even with destructiveHint and idempotentHint=false in annotations, the description adds concrete failure modes and mutation semantics. The behavior is described in enough specificity that the agent can predict side effects before calling.

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

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

The text is long and dense, but it is coherently organized around core purpose, then upsert semantics, then build hints, then enforcement/escape hatch. Almost every sentence adds a new behavioral fact, though a few clauses repeat details already present in the schema. It is not short, but it earns most of its length given the complexity of a 9-parameter, nested-object write operation.

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

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

For a tool with no output schema, the description thoroughly covers what the result carries: consistency warnings, carried_forward fields, build_hints, refusal errors, and how audit_taste later uses the binding. It also covers edge cases like re-binding, uncalibrated_ack carry-forward, explicit empty clears, and consistency-checking against captured references. The most important pitfalls are all front of the agent: persistence location, refusal conditions, and post-bind effects.

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

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

The schema is fully covered, but the description still adds high-value parameter nuance beyond field names: that references are not prose but captured live and consistency-checked against design_notes, that overrides use 'off' to silence a rule, that design_notes keys are normalized and trimmed dimension names, and that uncalibrated_ack is an escape hatch with strict gatekeeping. It tells the agent how parameters combine and what result they inform. This goes well above the baseline 3 one would expect for 100% schema coverage.

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

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

The description opens with a precise verb and object — 'Persist a project's surface calibration for a taste profile' — and immediately ties the input to the outputs of get_taste_interview. It distinguishes the tool from siblings like audit_taste by explaining that this is the binding step, not the audit application step. It also enumerates exactly what is stored (surface, hosts, overrides, voice_note, design_notes, references), leaving no ambiguity about the tool's role.

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

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

The description gives an explicit workflow: 'Run get_taste_interview, ask the USER, and bind their answers.' It also names audit_taste as the later step that consumes the binding, and warns against using uncalibrated_ack as a workaround. The escape hatch is precisely scoped to users who were interviewed and deliberately skipped every dimension, which is strong when-versus-when-not guidance.

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

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

The description thoroughly discloses side effects: it stores a JSON record under ~/.raven/references, truncates html over 8000 chars, rejects style maps over 200 properties, rejects non-http(s) URLs, gives every record a fresh ref_id, and attempts an offline PNG thumbnail with best-effort fallback. The annotations only say destructiveHint=true; the description carries the full behavioral burden and does it well.

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

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

The description is dense but each sentence adds useful context: invocation order, storage behavior, truncation/rejection rules, thumbnails, and exclusions. It is slightly long, but the length is justified by the number of behavioral caveats an agent needs to know before calling a capture-and-persist tool.

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

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

For a 12-parameter mutation tool with no output schema, the description covers the essential ground: what gets persisted, where, what constraints apply, what happens if the browser is unavailable, and which related tools handle adjacent concerns. It doesn't state the response shape beyond mentioning ref_id, but an agent can call the tool correctly without that detail.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by telling the caller to pass fields exactly as returned from get_grabbed_elements and by highlighting runtime constraints on html length, style property count, and URL scheme. It doesn't add much on parameters like owner or tags, but the schema already explains those clearly.

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

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

The description opens with a clear verb and resource: 'Persist a pattern grabbed from any page so it survives the browser tab.' It also explicitly distinguishes itself from map_reference_to_tokens by stating what it does not do, so an agent can tell which tool to use without opening the schema.

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

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

The description gives an explicit call sequence: call it after get_grabbed_elements returns a selection, and pass that selection's selector/styles/html/rect/stateStyles plus the URL. It also gives a negative case: mapping onto project tokens belongs to map_reference_to_tokens, and this tool does not fetch the source URL.

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

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 description states that this saves a source-file configuration, which adds some context about persistence. However, it does not mention that this overwrites an existing configured source or how the change affects future inventory/diff operations; the destructiveHint annotation is carrying most of the risk disclosure.

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

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

The single sentence is short, front-loaded with the action verb, and clearly communicates the central purpose. It loses little from being more structured, example, or explaining the .raven config location.

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

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

With 5 parameters, a nested object, and no output schema, the description is rather minimal. The schema fills most knowledge gaps, but the description would benefit from noting the persistent/overwriting nature of the action, any required environment ordering (for example ensuring DESIGN.md exists), or how aliases relate to the source file.

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

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

Schema coverage is 100%, so the schema fully documents project_dir, source_kind, platform, aliases, and design_file_path. The description only adds the fact that the design file is local and used for inventory/comparison, which contributes little beyond the schema.

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

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

The description clearly states the action ('Save') and the target resource (the local DESIGN.md file Raven should use), and it connects to the tool's inventory/comparison purpose. It differentiates the tool from generic read/update operations but does not explicitly distinguish it from sibling configuration-like tools such as update_design_md.

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

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

The intent of using this during setup for design-system inventory/comparison is implied, but there is no explicit 'use this when' guidance, no exclusion for editing/reading DESIGN.md, and no comparison to alternatives like update_design_md or read_design_md.

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

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

Beyond the annotations, the description discloses that profiles are stored locally under ~/.raven/creative by default and that the tool both creates and updates profiles. This adds useful side-effect context. Nothing in the description contradicts the destructiveHint annotation; 'update' reasonably implies possible overwrite behavior.

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

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

Two short sentences deliver the action, resource, purpose, key stored fields, and the default storage location. There is no filler or repetition of annotations, and the primary statement is front-loaded.

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

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

Given full schema coverage, a single required parameter, and the absence of an output schema, the description is sufficient for an agent to invoke the tool correctly. It provides the storage default and purpose, though it could theoretically add more detail about update/overwrite semantics or the response shape.

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

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

The input schema has 100% description coverage for all parameters, so the schema already carries the semantic load. The description's field list mostly mirrors what the schema already documents rather than adding deeper parameter-level meaning. This is the expected baseline when schema coverage is high.

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

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

The description states a specific action ('Create or update') and a clear resource ('local brand profile used by Raven creative jobs'), then lists what the resource stores. This makes it easy to distinguish from read/list siblings like get_brand_profile or list_brand_profiles, and from create_character_profile.

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

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

The description gives clear context: this is for creating or updating a local brand profile for Raven creative work. It does not explicitly name alternatives or state when not to use it, so it stops short of the strongest possible guidance, but the intended context is still clear.

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

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

Annotations already indicate a write operation and destructive potential. The description adds non-obvious context by explaining that Raven only stores reference asset IDs and provider-training payloads locally, and that no actual identity training occurs in this step. It does not detail overwrite behavior for existing profiles, but the destructive hint covers that signal.

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

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

Two sentences with the core action front-loaded and the key scope boundary clearly stated in the second sentence. No wasted words or redundant restatement of the schema.

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

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

The description, combined with 100% schema coverage and annotations, gives an agent enough to understand the tool's purpose, side effects, and limitations. The only notable gap is the lack of any statement about what the call returns, such as the created profile ID, but the optional stable id parameter partially mitigates that.

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

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

Schema description coverage is 100%, so parameters are already well documented. The description adds slight context by connecting reference_asset_ids and provider-training payloads, but it does not materially expand on the schema's per-field descriptions. Baseline 3 is appropriate.

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

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

Opens with a specific verb and resource: 'Create a local character/identity reference profile for consistent image or video generation.' This clearly distinguishes it from siblings like create_brand_profile and create_taste_profile, and clarifies it is creating a local reference profile rather than a trained identity.

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

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

The description makes the main use case clear: create a local profile for consistent image or video generation. It also explicitly excludes the major confusion point: 'actual identity training happens only through a configured provider runner.' It does not name sibling tools, but the boundary is clearly drawn.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, and the description adds useful behavior beyond that: if execute=true and RAVEN_CREATIVE_RUNNER is configured, the job is submitted to that runner. It also tells the agent that a 'brand-aware provider payload' is returned, which is extra useful context.

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

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

The description is concise: three sentences that front-load the core purpose and then provide return type and conditional behavior. There is no fluff or redundant restating of the schema.

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

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

Given a large 15-parameter surface and no output schema, the description covers the main decision factors: what kind of jobs it supports, what it returns, and when an execution side effect occurs. It could still mention the exact shape of the returned payload or what happens when execute=false, but it is adequate for a capable agent to proceed.

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

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

The schema already documents 100% of the 15 parameters, so the description doesn’t need to go through each one. It adds some context around media types and the execute/runner flow, but it does not introduce new meaning to individual fields.

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

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

The description states a specific verb ('Create') and resource ('a Raven creative generation job') and lists the covered media types (image, video, 3D, audio, campaign, analysis). It clearly separates from retrieval siblings like get_generation_job and list_generation_jobs, though it does not name alternatives.

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

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

The description implies usage when a new Raven generation job is needed and overlays the execute=true/RAVEN_CREATIVE_RUNNER condition. However, it does not explicitly provide when-to-prefer-this tool versus related siblings such as plan_creative_campaign, score_creative, or list_creative_presets.

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

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

Annotations already signal destructive behavior, but the description goes further by specifying the profile can be overwritten, where it is stored, how the storage directory can be overridden, the merge order of template vs explicit rules, and that the operation is local-first with nothing leaving the machine.

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

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

The description is dense but every sentence earns its place. It front-loads the core action before diving into format details, and organizes the complexity in a single cohesive flow rather than padding with filler. The exclusions and caveats are integrated without repetition.

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

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

For a create/overwrite tool without an output schema, this description is complete: it covers accepted inputs, markdown rules format, template bootstrap, precedence/merge order, storage location, overriding the directory, and necessary follow-up steps. The addition of a warning against non-rule-shaped docs contextual makes this especially strong.

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

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

Even with 100% schema coverage, the description meaningfully enriches parameter semantics: it explains markdown ingestion syntax, severity marker conventions, rule delegation syntax, scope markers, negative-prompt behavior, and template merge order. This goes well beyond the raw JSON schema.

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

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

The description opens with a precise verb and resource: 'Create (or overwrite) a named taste profile'. It then defines what a taste profile is, where it is persisted, and how it differs from related concepts like getting or interviewing a taste profile, making the tool's purpose unambiguous.

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

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

The description gives explicit input-mode guidance: pass rules[], pass markdown, or pass a template. It tells the agent when the template is appropriate, warns that brand-story docs should not be ingested, and explicitly says to run get_taste_interview afterward because a template is a floor, not a substitute for calibration.

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

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

Annotations already establish that the action is mutating and destructive, and the description's 'add' aligns with that. It adds useful context that the decision is 'active' and stored in the 'local' Decision Graph, but it does not disclose side effects such as whether an existing active decision is overwritten or superseded.

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

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

The description is a single, front-loaded sentence with no filler or repetition. Every word contributes to defining what the tool does.

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

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

For a mutating tool with six parameters and no output schema, the description is accurate but minimal. It does not explain what being an 'active decision' means or how this call relates to the decision lifecycle, so an agent can invoke it but not fully anticipate its consequences.

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

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

The schema already provides 100% parameter coverage, describing each field including scope, statement, component_ref, rationale, author, and alternatives_rejected. The description adds no disambiguation beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a clear verb ('Add') and a specific resource ('an active decision to the local Decision Graph'). It communicates that the tool creates a decision record, but it does not explicitly contrast itself with sibling tools like decision_commit, decision_draft, or decision_import, so its scope is slightly dependent on inference.

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

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

The description gives no guidance about when to use this tool instead of the many related decision tools. It implies that you call it when you need to add an active decision locally, but it does not mention alternatives, exclusions, or prerequisites.

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

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

Annotations already mark readOnlyHint false, destructiveHint true, and idempotentHint true, so the description does not need to repeat those. It adds a 'commit/confirm' semantic but does not disclose what happens to the existing draft, whether rationale is overwritten, or what a successful call returns.

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

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

The description is a single purposeful sentence with no filler. Every phrase contributes: the action, the object, and the target decision state are all included.

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

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

Given the parameter schema and annotations, the definition is enough for basic invocation, but not complete for a mutation tool. There is no output schema, and the description does not clarify what 'commit' does to the decision lifecycle, so an agent must infer side effects and return behavior.

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

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

The schema already describes all three parameters fully, so the description is not heavily burdened here. It reinforces 'rationale' as the confirmed rationale, but adds no extra meaning for 'id' or 'similarity_threshold' beyond the schema.

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

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

The description names a concrete action ('commit or confirm') and a clear object ('the rationale for a decision'), so the purpose is understandable. It also scopes the target to 'draft or extracted' decisions, but it does not explicitly differentiate itself from the many sibling decision_* tools such as decision_draft or decision_evidence.

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

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

'For a draft or extracted decision' gives a useful usage context, but it does not say when this should not be used or mention an alternative among the decision_* family. The intended workflow position is implied rather than spelled out.

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

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

Annotations already declare the operation as non-read-only and destructive, and the description meaningfully adds the concrete consequence: the decision stops governing immediately. It also discloses what does not happen, no deletion and no replacement requirement, reducing the risk of over-assuming side effects. It does not explain reversal or post-contest state, but the immediate behavioral consequence is well stated.

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

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

The description is one sentence that front-loads the action and outcome, then adds two key exclusions. There is no filler, no repeated schema details, and no over-explanation. It earns high marks for conciseness and structure.

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

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

For a 3-parameter destructive operation with annotations and a rich schema, the description gives the essential state information: contesting, active, stops immediately, no deletion, no replacement. It would be slightly more complete with an explicit note about the return value or resulting decision state, but the agent can safely call the tool with the provided information.

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

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

The input schema covers 100% of parameters, and each parameter already has a clear description including the graph-edge effect for evidence_ref. The tool description does not add extra parameter-level guidance, which is fine because the schema carries that burden. Baseline 3 is appropriate here.

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

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

The description uses a specific verb ('contest') and resource ('active decision'), and states the concrete outcome: the decision stops governing immediately. It also distinguishes the operation from deleting or superseding by explicitly saying it does neither. This is enough to separate it from the many decision_* sibling tools.

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

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

The description implies the correct usage: contest an active decision, especially when replacement is not intended. It provides a clear precondition ('active') and an implicit contrast with supersede, but it never explicitly names when to use this tool instead of decision_supersede, decision_evidence, or decision_commit. The usage guidance is present but left to inference.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=true, and the description adds the useful behavior that the reason is intentionally left out at draft time. It does not clarify what side effects occur, whether an existing draft is overwritten, or what 'later confirmation' concretely requires.

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

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

The description is one clean sentence with no filler, and the most important behavior, 'Capture a decision,' is front-loaded. The deferred-rationale clause earns its place by clarifying that this is a draft action.

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

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

The core action and the deferred-rationale behavior are present, and the input schema covers all parameters. However, with no output schema and a destructiveHint=true annotation, the definition leaves the concrete result of the operation and the handoff to finalization tools like decision_commit somewhat ambiguous.

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

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

The schema fully documents all four parameters, so the description does not need to repeat their syntax. The description usefully signals that a 'why' field is absent by design, but it adds no per-parameter information beyond what schema descriptions already provide.

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

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

The description names a specific action ('Capture a decision') and a source/context ('working context'), and it clearly signals the provisional nature by saying the rationale is deferred for later confirmation. It does not explicitly distinguish itself from the sibling decision tools like decision_commit or decision_add, so full differentiation is left mostly to the tool name.

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

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

The phrase 'why deferred for later confirmation' implies this is for interim decisions that are not fully reasoned yet, which gives some usage context. However, it never explicitly says when to use this versus decision_commit, decision_add, or decision_supersede, nor does it state when not to use it.

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

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

Annotations already mark the tool as not read-only and as destructive, so the description does not need to re-establish the mutation profile. The description adds that the target must be an existing decision, but it does not disclose behavior like whether the evidence is appended, replaces prior evidence, or what side effects may occur.

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

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

A single compact sentence contains the key action, resource, and scope. It is front-loaded and contains no filler words or redundant qualifications.

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

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

With six parameters, no output schema, and a mutation-focused sibling suite, the description gives the minimum viable context. It identifies the action and target, but leaves behavior details such as validation failure modes, return value, and interaction with decision history unstated. Annotations cover some of the safety gap, but this is not complete enough for complex tool-use routing.

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

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

The input schema has full coverage with descriptions for all six parameters. The description adds nothing to parameter meaning beyond the schema, so the baseline score of 3 is appropriate. 'Quantitative or qualitative' adds no extra semantic weight because type enum already captures this.

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

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

The description uses a specific verb ('Attach') and clearly identifies both the object (evidence) and the scope (an existing decision). It distinguishes itself from creating decisions through the word 'existing', though it does not explicitly name or reference sibling alternatives.

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

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

The context is implied: use this when attaching quantitative or qualitative evidence to an existing decision. It does not explicitly describe when not to use it or which sibling tools to use instead, such as decision_add for creating decisions or decision_commit for finalizing them.

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

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

Annotations already provide destructiveness and read/write hints, so the agent is warned that this is not a pure read operation. The description does not contradict the annotations, but it also does not explain why a 'get' operation is flagged destructive or what exactly may happen to the graph when the node is fetched.

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

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

The description is a single compact sentence that puts the verb and resource first and contains no redundant filler. Every word contributes to the meaning of what the tool returns.

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

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

The description does state the main output shape: the node and all nodes connected to it by edges in either direction. But there is no output schema, so the agent still lacks detail about how edges, directions, or node data are returned, and the destructive annotation is left unexplained.

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

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

The only parameter is fully described by the schema: id is the Decision Graph node id. The description adds only the slight extra meaning that id is the starting node from which connected nodes are followed, so it has limited additional value.

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

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

The description names a concrete operation ('Get'), a specific resource ('a Decision Graph node'), and a clear output shape ('every node connected to it by an edge in either direction'). It is specific enough to distinguish the tool from the many decision_* siblings without needing to inspect their schemas.

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

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

The description implies when to use the tool: when the agent needs a decision graph node and its graph-connected neighbors. However, it does not explicitly state when to prefer it over closely related sibling tools such as decision_list or decision_history, nor does it give any excludes or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is covered. The description adds context about complete lineage and chronological ordering, which is useful but not extensive. No contradiction with annotations.

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

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

The description is a single focused sentence with no filler. The core behavior is front-loaded, and the ordering detail is placed efficiently without redundancies.

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

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

This is a simple read-only tool with one well-documented parameter and no nested schemas. The description adequately explains what the tool does and its output ordering. It could mention what shape the lineage takes, but given the low complexity, it is reasonably complete.

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

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

Schema description coverage is 100% and the 'id' parameter is already well-documented as an existing decision id anywhere in the lineage. The description adds no meaningful parameter semantics beyond what the schema provides, so the baseline 3 applies.

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

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

The description uses a specific verb ('Return') and identifies the resource ('complete supersession lineage for a decision') with ordering detailed. This clearly differentiates it from siblings like decision_get or decision_list, which focus on individual decisions or lists, so an agent can tell them apart.

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

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

The description makes clear the tool is for retrieving the full lineage of a decision, but it does not explicitly state when to prefer it over alternatives such as decision_get, decision_list, or decision_evidence. The context is implied rather than explicitly articulated.

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

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

The description adds one meaningful behavioral beyond annotations: imported history is review-only until decision_commit. That is valuable. However, annotations mark this tool as destructive and readOnly=false, and the description does not explain what (if anything) gets changed, overwritten, or destroyed, or why it is unsafe. It does not directly contradict the annotation, but it also does not clarify it.

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

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

Two concise sentences in 24 words: the first states the core operation at front, and the second adds the workflow gate. Every sentence has a direct purpose, with no fluff.

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

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

The schema covers parameters and there is no output schema to explain. The description gives overall behavior and the review-only boundary, but remains thin on how the resultant prompts are delivered and what the destructiveHint means in practice. A capable agent could make the call, but would be guessing about side effects and outputs.

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

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

Schema description coverage is 100%, so all four parameters are already adequately documented. The tool description adds no per-parameter meaning, such as how repo_path, doc_globs, max_commits, or max_chunk_chars affect the extraction, but the schema provides the necessary baseline.

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

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

The first sentence uses a specific verb ('Mine') and resource ('local git history and decision-bearing Markdown'), and states the output is 'provenance-tagged Decision Graph extraction prompts.' It is clear but does not explicitly differentiate itself from the many sibling 'decision_*' tools, so it earns a 4 rather than a 5.

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

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

The phrase 'remains review-only until decision_commit' gives useful workflow context, implying this tool is the staging step before decision_commit. However, it never explicitly states when to use this tool versus sibling alternatives, nor does it give conditions to avoid it, so usage guidance is only implied.

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

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

The description presents an apparently read-only listing operation, but the annotations declare readOnlyHint:false and destructiveHint:true. The description does not mention this destructive character or any side effect of listing decisions. This is an Annotation Contradiction.

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

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

The description is compact and front-loaded, with every sentence adding useful guidance. The semantic explanation of 'contested' status and the final heuristic about missing decisions are both purposeful, not filler.

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

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

The description makes the core selection semantics clear, including the non-obvious contested-decision behavior. It does not describe pagination, sort order, or exact return shape, but the operation is simple enough that 'list decisions' implies a list return, and the parameter schema covers the optional knobs.

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

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

All four parameters already have schema descriptions, so the baseline can be 3. The prose adds meaningful interpretation by explaining why contested decisions are excluded from the default and how to opt into seeing them. It does not deepen drafts_only/include_candidates, but the schema already covers those.

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

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

The description opens with a specific verb and resource: 'List decisions in the local Decision Graph.' It immediately clarifies the default scope (ACTIVE decisions only) and defines what 'active' means — decisions that currently govern — which distinguishes this listing tool from single-decision tools like decision_get.

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

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

It gives explicit guidance on how to adjust the default behavior: omit status for active decisions, pass status:'contested' to review disputes, or use include_contested:true to see both. It does not compare against sibling decision tools, but it does clearly explain the main filtering alternatives and the contested-decision rationale.

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

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

The description aligns with annotations: destructiveHint=true, readOnlyHint=false, and idempotentHint=false, indicating this is a mutating operation. It clarifies that scopes are narrowed and the likely effect is that both decisions stay active, but it does not disclose side effects, whether previous scopes are overwritten, or what happens if the scopes are not actually distinct.

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

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

The description is a single focused sentence with no excess wording, repeating, or structural clutter. It presents the core action and intended result front-loaded and reads clearly.

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

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

For a four-parameter mutating tool with no output schema, the description is reasonably complete but leaves some practical gaps: it does not define what a valid 'scope' looks like, whether the two scopes must be non-overlapping, or what the agent should do before/after calling. The full schema and annotations help, but a little more conceptual context would make this tool safer to use.

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

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

Schema description coverage is 100%, so all four parameters already have meaningful descriptions: id_a/id_b identify existing decisions and scope_a/scope_b are the narrowed scopes. The tool description adds no extra parameter-level guidance, which is acceptable because the schema already carries the full semantic load.

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

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

The description uses a specific verb ('narrow') with a clear resource ('two decisions' and their 'scopes') and the intended outcome: both decisions can remain active. This distinguishes it from generic get/list/commit tools, though it does not explicitly name sibling tools like decision_supersede or decision_contest.

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

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

The phrase 'so both can remain active alongside one another' implies when this tool should be used: when two decisions would otherwise conflict or overlap and both need to be kept. However, it gives no explicit guidance about when not to use it or when to prefer a sibling tool such as decision_supersede.

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

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

The description adds useful behavioral context beyond the annotations by stating that both decision nodes and their lineage are preserved. This helps an agent understand that the operation is not a simple deletion even though destructiveHint is true. It does not contradict the annotations and gives a meaningful guarantee about what survives the operation.

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

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

The description is a single concise sentence that leads with the core action and then explains the important preservation guarantee. There is no wasted text, jargon, or repetition of the schema. Every phrase earns its place.

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

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

Given the tool's simple two-parameter surface, the absence of an output schema, and the annotations covering mutation/destructive behavior, the description is reasonably complete. It tells the agent what kind of relationship to create while assuring that the original nodes remain intact. It could say more about side effects or return values, but for this tool's complexity it is adequate.

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

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

The input schema already provides full descriptions for both required parameters, old_id and new_id, with 100% coverage. The description does not add extra parameter-level detail, but none is necessary because the schema carries the semantic weight. It correctly implies that these are the two existing decisions involved in the supersede operation.

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

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

The description clearly states the tool's verb and resource: 'Explicitly supersede one decision with another.' It also adds a meaningful qualifier that both nodes and lineage are preserved. However, it does not explicitly differentiate itself from related sibling tools like decision_commit or decision_scope, so an agent gets semantic clarity but not direct sibling routing.

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

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

There is no guidance about when to use this tool versus the other decision_* siblings. The description implies the obvious use case—superseding an old decision with a new one—but never states exclusions, prerequisites, or alternatives. An agent must infer the intended context from the tool name and description alone.

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

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

The annotations already mark it read-only and idempotent, and the description adds substantial behavioral context on top: both pages are rendered headless and measured from live computed CSS, never from recall. It also discloses the reference-guardrail behavior (don't copy the reference's copy, marks, imagery, or brand color), which is exactly the kind of behavioral nuance annotations cannot express.

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

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

The text is long but dense, and every sentence contributes: input, measurement method, dimensions, outputs, the on_par loop, and the standard-vs-source rule. It loses a point only for being a single unwieldy paragraph rather than a more scannable structure.

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

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

With no output schema present, the description thoroughly enumerates the full return shape: both raw measurements, per-dimension diffs, concrete derived bars, a human-vs-mechanical fix list, and the on_par boolean. Combined with the loop usage, this is remarkably complete for a tool with nested parameters and nuanced measurement behavior.

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

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

The schema already covers all parameters, so the baseline is high. The description adds semantic weight by clarifying that subject_url is the page being improved, reference_url is the benchmark whose values derive the bar, and that both are measured the same live way. This qualifies the meaning of the parameters beyond their schema descriptions.

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

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

The description names the exact question it answers, defines the tool as a live, headless comparison of a subject page against a reference page, and enumerates the nine measured dimensions. This clearly differentiates it from sibling audit or scoring tools because the core is comparative benchmarking with a verdict boolean.

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

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

The description explicitly places the tool inside a loop: build, critique against renders, re-run, and only consider work done when verdict.on_par is true. It also gives a clear rule for interpreting the reference page — a standard, not a source — though it doesn't name alternate sibling tools or give explicit when-not-to-use cases.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral detail by specifying exactly what kind of report is produced, what categories of drift are surfaced, and that output includes fix priorities. No contradiction with annotations.

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

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

The description is one compact, front-loaded sentence. It starts with the core action and resource, then efficiently enumerates report contents without repeating schema details or including fluff.

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

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

No output schema exists, so the description carries the burden of explaining return value: it lists report categories and says the result is scored with fix priorities. It does not explain required setup or output format, but since there are no required params and the setup is referenced by the schema, the description is reasonably complete.

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

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

Schema description coverage is 100%, so the schema already documents all four params. The description mainly restates the general 'project/system vs baseline' concepts rather than adding new detail about platform, project_dir, or design_file_path semantics.

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

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

Description uses a specific verb ('Diff'), names the resource (project's declared design system vs Raven canonical baseline), and lists concrete outputs (missing components/states/variants, token drift, fix priorities). It is clearly distinguished from sibling read-oriented tools by its comparison/diff intent.

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

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

The use case is implied: use this tool when you need to compare a project design system against the Raven canonical baseline. However, it does not mention any alternatives or exclusion cases, so it relies on the agent inferring when other read/inventory/design-system tools might be better choices.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool produces principles, violations, and improvement suggestions, but it does not add behavioral detail such as output size, the meaning of compact mode, or the before/after diff behavior. No contradiction with annotations exists.

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

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

The description is a single tight sentence with no filler, front-loading the core action and then listing the three output categories. It earns its place and avoids duplicating schema details.

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

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

With six optional parameters and no output schema, the description leaves important context implicit: it does not explain whether a text description, screenshots, or both are needed, nor does it describe the structured pixel diff returned when both before and after screenshots are supplied. The compact mode payload rationale is only present in the schema, not reflected in the description, so an agent has to infer key invocation behavior.

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

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

Schema description coverage is 100%, so the schema already documents each parameter clearly. The main description adds no new parameter-level semantics beyond the general 'evaluate design' idea. This fits the baseline score of 3 for a tool whose schema has fully documented parameters.

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

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

The description uses the specific verb 'Evaluate', names the resource ('design description'), and binds the operation to 'UX principles'. It also states the return contents: relevant principles, potential violations, and improvement suggestions. It does not explicitly distinguish itself from the many audit_* siblings, but the wording is specific enough that an agent can infer its intent.

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

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

There is no guidance about when to choose evaluate_design over the many related audit_* or get_* tools. No conditions, exclusions, or alternative tool names are mentioned, so an agent must infer the appropriate context from the tool's name and generic description.

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

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

Beyond the annotations' destructiveHint, the description adds substantive behavioral context: irreversibility, no trash, exact host-with-subdomains matching, domain matching edge cases, local-only scope, and 'contacts nobody'. It also discloses response behaviors like appeared_since_preview, skipped, and failed results. No contradiction with annotations is present.

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

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

The description is long, but every clause carries contractual detail: target mode, irreversibility, host-matching semantics, expected_ref_ids behavior, return channels, and edge cases. It is front-loaded with the essential action and structured to communicate complex destructive behavior without flat phrases.

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

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

With no output schema, the description compensates thoroughly by specifying every relevant return channel (ref_ids, appeared refused, skipped, failed) and the failure semantics (unparseable JSON, non-deletable records). It also covers all four parameters and the main destructive edge cases, so an empty element can execute it correctly and understand partial results.

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

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