MotionSpec — verified web motion (reduced-motion / WCAG)

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

The description explicitly says 'Does network I/O (openWorldHint)' while the annotations declare openWorldHint: false. This is a direct contradiction. It otherwise adds useful details such as the paid-plan requirement and the exact return object, but the contradiction forces a 1 per the scoring rubric.

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?

Dense but well organized: prerequisite is front-loaded, the four checks are numbered, runtime limitations are disclosed, and the return shape is compactly listed. It is longer than the average description, but nearly every clause carries useful information.

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

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

Given a single parameter and no output schema, the description covers inputs, the four audit criteria, the runtime limitation, the return object, and the badge criterion. It doesn't explain score ranges or findings structure, but for this tool's complexity it is largely complete. The openWorldHint contradiction is a notable correctness gap.

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

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

Schema coverage is 100% and the only parameter, url, is already described in the schema as 'The page URL to audit (http/https)'. The description adds context about fetching the URL's HTML and stylesheets but does not add new parameter-level constraints or semantics 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?

States a specific verb ('audit'), resource ('a live URL'), and the exact accessibility goal (motion accessibility, WCAG 2.2.2 / 2.3.3). It enumerates four distinct CSS checks, making the tool's scope unambiguous and separating it from sibling tools by explicitly marking it as a static checker.

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?

Clearly frames the tool as a static CSS-only motion-a11y checker, notes that runtime motion (WAAPI/GSAP/JS) is not audited, and gives a pricing prerequisite. It does not explicitly name alternatives or state when not to use it, but the static-vs-runtime distinction is strong contextual guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's claim of 'returns the catalog' is consistent and adds no contradiction. The description provides extra context such as free check links and pricing for the hosted endpoint, which is useful for the agent to understand external dependencies. Since the read-only behavior is already covered by annotations, the extra content is a positive addition, though not strictly behavioral.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by ordering guidance and external links. It is three sentences and relatively efficient; the pricing link and 'free motion check' are somewhat tangential to the tool's invocation but still useful context. The structure is clean and not overly verbose, so a 4 is appropriate.

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 carries the full burden of explaining the result content. It clearly states that the catalog includes names, purpose, parameter schemas, and defaults, plus authoring rules. It also gives order-of-use and validation guidance, which is essential for the agent. The description is sufficient for an agent to know what to expect and how to use the tool first.

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

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

The tool has zero parameters, so the description adds no parameter-specific semantics. With schema coverage at 100% (vacuously), the baseline for zero parameters is 4, and no additional parameter explanation is needed. The description's mention of 'parameter schemas' in the catalog result is context, not parameter documentation.

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

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

The description clearly states the tool's function: returning a catalog of motion primitives with names, purpose, parameter schemas, defaults, and authoring rules. It explicitly names motion_validate as the validation step, providing some sibling differentiation. However, it does not contrast with motion_audit, motion_stats, or motion_compile, relying mostly on their distinct names and the 'call this FIRST' instruction to distinguish them.

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 instructs 'Call this FIRST, then write the spec yourself and validate it with motion_validate,' giving very clear ordering and next steps. It also indicates that motion_compile requires a CLI or a hosted endpoint key, which informs the agent about downstream usage requirements. It does not contain any when-not-to-use conditions or alternatives beyond the one sibling mentioned, but the overall guidance is effective.

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/openWorld annotations, it discloses determinism, fail-closed validation, reduced-motion enforcement, performance reporting, and the exact return shape ({ok, js, css, report} or {ok:false, errors}). No annotation contradiction exists.

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

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

Four dense sentences contain no filler, and the critical operational constraints (cost/local option, validation, output) are each conveyed once. The return contract is compactly and clearly stated.

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 deterministic compiler tool, the description covers prerequisites, local alternative, validation semantics, output artifacts, and error form even without an output schema. An agent has enough to select and invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents spec and specName. The description does not add parameter-level detail beyond the schema, which is acceptable but not value-adding; 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 concrete action (deterministically compiles) and resource (MotionSpec) with a specific output (vanilla-GSAP JavaScript and CSS). It clearly differs from sibling tools like motion_validate or motion_audit by stating it produces code, not just validation or analysis.

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 prerequisites (hosted Dev Key/Agency plan vs free local npx command) and states fail-closed behavior, which tells an agent when the compile will fail. It does not explicitly name sibling alternatives or say when to prefer motion_validate/audit, so it stops 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 mark readOnlyHint=true, and the description adds access/plan requirements and clarifies the output type ('counts per outcome'). This goes beyond the structured fields without contradicting them.

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

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

Three short sentences, each carrying relevant information: access requirement, telemetry summary, and interpretation of escalation clusters. The core purpose is slightly delayed by the pricing sentence, so it is not fully front-loaded.

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

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

For a zero-parameter read-only tool without an output schema, the description covers access, the response shape in broad terms, and the meaning of escalation clusters. It would be more complete with a little more detail on the shape of the response, but it is sufficient for invocation.

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

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

There are no parameters to document, so the baseline of 4 applies. The description does not need to add parameter-level meaning.

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

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

The description states a clear resource — routing/compile telemetry — and defines the result as a summary with counts per outcome. It is distinguishable from siblings via the word 'telemetry', though it does not explicitly contrast with motion_audit or motion_validate.

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

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

Usage context is implied: 'Escalation clusters indicate which new primitive the catalog needs next' suggests it is for catalog planning, and the Dev Key/Agency plan requirement sets access conditions. However, there is no explicit 'when to use vs motion_audit/motion_validate' guidance or exclusion of 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?

The description goes well beyond the readOnlyHint annotation by disclosing fail-closed behavior ('returns ok=false with precise errors') and the critical warning semantics that warnings[] can be non-empty while ok=true, tying it to WCAG 2.2.2/reduced-motion. This is genuinely valuable behavioral context that annotations alone do not provide.

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

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

The description is dense and efficient: the first sentence states the core action, the second explains fail-closed and returns, and the third highlights the critical accessibility nuance. Every sentence earns its place with no redundant or filler 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?

Despite having no output schema, the description explicitly enumerates the return shape ({ok, errors, warnings, deprecations, catalogVersion}) and explains the non-obvious semantics (warnings non-empty with ok=true). Combined with the single well-documented parameter and clear annotations, this gives an agent everything needed to invoke and interpret 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?

The input schema already has 100% coverage for the single 'spec' parameter with a description, so the baseline is 3. The tool description adds high-level validation context (what is checked) but does not add specific parameter syntax or formatting details beyond the schema, so no score above the baseline is warranted.

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 ('Checks') and clearly identifies the resource being validated (a MotionSpec), listing the exact validation dimensions: schema, primitive allow-list, parameter bounds, and injection rules. This also distinguishes it from the sibling motion_catalog by making clear this is a validation/trust-boundary tool, not a catalog lookup.

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

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

The description provides explicit guidance on when to use the tool: 'Use to pre-check a spec before compiling.' This gives clear context and a practical usage trigger. It does not explicitly name alternatives or state when not to use it, but the guidance is strong enough for an agent to select it appropriately.

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