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

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

The annotations declare openWorldHint=false, yet the description explicitly states the tool fetches a URL's HTML and stylesheets and closes with '(openWorldHint).' That is a direct contradiction of the structured hint and could cause an agent or host to under-provision network egress/permissions. The description is quite likely the accurate party (it genuinely performs network I/O), but per the rubric a contradiction with annotations caps this dimension at 1.

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?

Front-loads the most decision-critical fact (the paid-plan requirement) and then packs a lot of high-value detail into a single paragraph. It is dense and parenthesis-heavy, which slightly impedes scanning, but almost every clause (statuses, exclusions, return shape, badge) 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?

With no output schema and no annotations the description must carry the full load, and it does: it lists the returned fields ({ok, score, status, findings, groups, summary, badge, disclosures, coverage, markdown}), the 'not-measurable' / null-score edge case, the 'review' classification for spinners, and the badge semantics. An agent can interpret results without further documentation.

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 is a single parameter and schema description coverage is 100%, so the schema already documents the url field and its http/https constraint. The description adds useful context about what the URL is used for (fetch HTML + linked stylesheets, cascade-aware scanning), but no additional syntax, defaults, or validation detail beyond the schema — 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?

States a specific verb+resource (audit a live URL for motion accessibility) plus the exact WCAG criteria (2.2.2 / 2.3.3) and enumerates the four detection rules, so an agent knows precisely what domain this covers. It also distinguishes itself from sibling static/runtime concerns by noting that runtime motion (WAAPI/GSAP/WebGL) is deliberately not audited.

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 clear preconditions and exclusions: requires a Dev Key or Agency plan, only works on the hosted endpoint, and is equivalent to the free site check. It also defines when a result is meaningful ('not-measurable' with score null when no CSS motion exists) and how spinners are classified. It does not, however, say when to prefer motion_audit over siblings like motion_validate or motion_compile.

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 safety profile is covered. The description adds real behavioral context beyond that: it is a bootstrap/discovery call that returns definitions rather than performing work, and it discloses that motion_compile requires the CLI or a hosted key.

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?

Front-loaded with what is returned, then the call order, then the compile caveat. The trailing promotional URLs (motion-check, pricing) are useful pointers but slightly dilute the definition; the substance is still tight and well ordered.

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 by enumerating the return contents (names, purpose, schemas, defaults) and the authoring rules. Combined with the sequencing guidance and the compile auth caveat, an agent has everything needed to use it correctly in the workflow.

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 takes zero parameters, so there is nothing for the description to document and the baseline of 4 applies. The description correctly implies no input is needed to retrieve the catalog.

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 (returns) and resource (the catalog of verified motion primitives) and enumerates the payload (names, purpose, parameter schemas, defaults) plus the authoring rules for a MotionSpec. It also implicitly distinguishes itself from siblings by naming motion_validate and motion_compile as downstream steps.

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 an explicit sequencing instruction ('Call this FIRST, then write the spec yourself and validate it with motion_validate') and clarifies where motion_compile actually runs (CLI or hosted endpoint with a key). An agent knows both when to call it and which sibling to use next.

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 only declare readOnlyHint and openWorldHint=false, so the description carries the burden and does so richly: auth/pricing prerequisites, fail-closed validation, determinism guarantee ('same spec always yields identical code'), enforced prefers-reduced-motion fallbacks, a performance-budget report, and the exact success/failure return shapes. Compiling is a pure computation, so readOnlyHint=true is consistent, not contradictory.

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 every clause earns its place, and the return contract is saved for last. It opens with licensing/pricing detail rather than the core action, which is slightly less front-loaded than ideal, and the second sentence is heavily parenthetical.

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, and the description compensates by naming the return shapes ({ok, js, css, report} or {ok:false, errors}), plus the guarantees an agent needs to decide whether to trust the output. Nothing material is missing for a two-parameter compile 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 no detail about the 'spec' object's expected shape or the 'specName' artifact header beyond what the schema already documents, and the nested free-form spec object remains opaque.

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

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

States a specific verb and resource ('deterministically compiles a MotionSpec into production-ready vanilla-GSAP JavaScript and CSS') and implicitly separates itself from motion_validate/motion_audit by covering both validation and code generation. An agent can distinguish this from siblings without opening 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?

Clearly states the conditions for the hosted endpoint (paid Dev Key or Agency plan) versus the free local CLI invocation, which is real usage guidance. It stops short of explicitly routing between siblings, e.g. it never says 'use motion_validate first if you only want errors' despite bundling validation.

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 safety is covered. The description adds non-obvious context annotations cannot carry: a paid-plan auth gate, the hosted endpoint, and an interpretation rule for escalation clusters. It does not describe granularity, freshness, or windowing of the counts.

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

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

Three sentences with no fat, but the front-loaded sentence is pricing and a promotional deep link (src=mcp) rather than what the tool does. The agent reads a plan price before learning the tool returns telemetry counts, which is suboptimal ordering for invocation decisions.

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

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

For a parameterless, read-only stats tool with no output schema, the description covers the access prerequisite, the shape of the return (counts per outcome), and how to interpret it. Only the time window and count granularity are left unspecified.

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 takes zero parameters, so there is no parameter semantics to document; the baseline of 4 applies. The schema is empty and fully covered, and the description correctly spends no words on inputs.

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 concrete deliverable: a summary of routing/compile telemetry with counts per outcome, plus an interpretation hook ('escalation clusters indicate which new primitive the catalog needs next'). That clearly separates it in spirit from motion_compile, motion_validate, motion_catalog, and motion_audit, though none of those siblings are named explicitly.

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

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

It discloses a real gating prerequisite (Dev Key or Agency plan on the hosted endpoint), which is genuine usage context, but it never says when to reach for this tool instead of motion_audit or motion_catalog. Usage is implied by the telemetry-summary framing rather than routed.

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 openWorldHint annotations by disclosing fail-closed behavior, the exact return shape, and the non-obvious fact that warnings can be non-empty while ok=true. It also explains the accessibility implication, which is critical for correct agent 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 and front-loaded, with the core validation behavior stated first, followed by the return shape and the critical warning caveat. Every sentence earns its place, and the formatting highlights the most important behavioral nuance.

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 single-parameter, read-only validation tool with no output schema, the description fully covers what the tool does, when to use it, what it returns, and the key failure and warning semantics. An agent has sufficient information to select and invoke it correctly without additional context.

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

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

Schema coverage for the single parameter is 100%, so the baseline is 3. The description adds meaningful semantics by clarifying that the spec parameter is a MotionSpec and by enumerating the validation dimensions applied to it, such as the primitive allow-list and injection rules, which the schema alone does not convey.

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

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

The description states a specific verb ('Checks') and a specific resource ('MotionSpec'), then enumerates exactly what it validates against: schema, primitive allow-list, parameter bounds, and injection rules. It clearly distinguishes itself from the sibling motion_compile by positioning validation as a pre-compile safety check.

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 to pre-check a spec before compiling,' which gives clear guidance on when to call this tool. It also explains the important warning behavior so an agent knows this is the right tool for accessibility checks before compilation, though it does not explicitly name or exclude alternatives beyond the pre-compile framing.

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