Designesy

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

With no annotations provided, the description fully discloses behavioral traits: it does not run scans server-side, requires a real browser DOM, and returns only checks and a script. This transparency ensures the agent understands the tool's limitations and execution mode.

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 paragraph that front-loads the core purpose. It includes all critical information but has minor redundancy (e.g., mentioning Playwright twice). Could be slightly tighter, but overall efficient.

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

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

While the description explains what the tool returns (checks and a script), it does not specify the exact response format or structure, which is important given no output schema. It adequately distinguishes from siblings but could be more precise about the output for full completeness.

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 baseline is 3. The description adds value by explaining that the URL is used to target the script template, the config is for axe.configure() customization, and the ruleset defaults to wcag22aa with listed options. This enhances understanding beyond schema descriptions.

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

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

The description clearly states the tool provides a WCAG 2.2 AA accessibility verification framework with specific conformance checks and a Playwright + axe-core script template. It explicitly distinguishes from the sibling tool designesy_score by noting it's for non-accessibility-focused scores.

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 states when to use the tool ('audit a site for accessibility violations') and when not to (use designesy_score for broader scores). It provides actionable guidance on how to execute the returned script locally, including npm and Playwright commands.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool is read-only and returns the agent.json object, which is sufficient for a simple parameterless read operation. It does not elaborate on potential errors or authentication needs, but these are reasonable given the tool's nature.

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

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

The description is two sentences, each serving a distinct purpose: stating what the tool does and providing usage guidance. It is front-loaded with the key action and remains free of unnecessary information.

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

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

The tool has no parameters, no output schema, but the description covers its purpose, return value, read-only nature, and a clear usage condition. It is complete for a simple discovery document retrieval tool.

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

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

The input schema has zero parameters with 100% coverage. Per guidelines, baseline is 4 when no parameters exist. The description does not need to add parameter details, and it correctly focuses on the tool's purpose.

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

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

The description clearly states the tool retrieves the Designesy agent discovery document (agent.json) and lists its contents. It distinguishes itself from the sibling tool designesy_catalog, which handles the package list alone.

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

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

Explicitly specifies when to use this tool: 'when integrating with or enumerating Designesy as a machine agent and need the canonical discovery/manifest endpoint rather than one specific contract.' Also provides an alternative tool for a related but different use case.

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

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

No annotations provided, but description declares 'Read-only' and details the returned catalog structure. No contradictions. Could mention auth or rate limits, but not necessary given simplicity.

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 concise sentences: action, usage guidance, output format. No unnecessary words; every sentence adds value.

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

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

Given zero parameters and no output schema, the description fully defines purpose, behavior, and return format. References sibling tool for contract content, completing the context.

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

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

No parameters in input schema, so schema coverage is 100%. Description adds meaning by describing the output structure, which is sufficient for a parameterless tool.

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 explicitly states it lists 12 published packages with versions, URLs, and statuses. Distinguishes from sibling designesy_contract by noting it provides catalog metadata, not contract content.

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 when to use ('to discover what Designesy publishes before fetching a specific contract') and provides an explicit alternative ('For the contract content itself, use designesy_contract instead').

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 no annotations provided, the description carries full burden. It discloses read-only nature, return format (full contract JSON or single section), and the available section options. Fully transparent.

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?

Well-structured with three clear sentences: purpose, usage guidance, and output description. Slightly dense but every sentence earns its place without redundancy.

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

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

Despite no output schema, the description covers inputs, output, usage context, and alternatives. For a simple single-parameter tool, this is fully sufficient.

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%, but the description adds value by listing all available section values (colors, motion, etc.) and explaining that omitting the parameter returns the full contract. This goes beyond schema 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 clearly states the tool retrieves the Designesy design-system contract with specific version and lists canonical elements. It distinguishes itself from the sibling tool designesy_score by specifying that this returns contract values while the sibling scores a URL against it.

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

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

Explicitly states when to use ('when you need actual contract values') and provides a direct alternative ('To score a live URL...use designesy_score instead'). No ambiguity.

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

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

The description states 'Read-only — the calling agent executes the review', clarifying it has no side effects. With no annotations provided, the description carries the full burden and adequately discloses behavior, though it could mention idempotency.

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

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

The description is two sentences, front-loading the core purpose and then clarifying usage. Every sentence adds essential information with no redundancy.

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

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

Given the tool's complexity (8-dimension rubric, optional inputs), the description covers output format (framework JSON or pre-filled prompt), lists rubric dimensions, and explains input behavior. No output schema exists, but description compensates. Could add more detail on JSON structure.

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 parameters have schema descriptions (100% coverage). The description adds value by explaining that providing parameters yields a pre-filled review prompt, versus returning the raw framework JSON. This semantic guidance goes beyond schema.

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

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

The description clearly states the tool retrieves the Designesy Design Review framework, an 8-dimension rubric. It distinguishes itself from sibling tool 'designesy_score' by noting it's for holistic critique, not numeric compliance.

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 when to use this tool ('when you want a structured rubric to critique a design holistically') and when not to ('rather than a numeric compliance score'), directing to 'designesy_score' for the latter. It also explains optional input behavior.

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 no annotations, the description carries full burden. It discloses 'Returns text/plain. Read-only.', which informs the agent of output format and safety profile. Could further detail side effects, but for a read-only fetch, this is sufficient.

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 redundancy. The first sentence immediately states the verb and resource. Every word adds value. Exemplary 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?

Given no output schema, the description specifies the return format (text/plain). The tool is a straightforward fetch, and the description covers purpose, contents, and usage context completely.

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 no parameters; schema coverage is 100% (empty). Per guidelines, baseline is 4. The description adds value by explaining what the returned content contains, but no param info 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 explicitly states the tool returns 'the complete agent-facing brief' and lists its contents (ingest protocol, discovery endpoints, etc.). It clearly distinguishes from the sibling tool designesy_llms_txt by indicating this is the full version for comprehensive onboarding.

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

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

Provides explicit when-to-use: 'for comprehensive onboarding... when the short /llms.txt is not enough.' And an alternative: 'For a quick orientation first, use designesy_llms_txt.' This gives clear decision 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?

With no annotations, the description carries full burden. It discloses return format (text/plain) and that it is read-only, which is sufficient for a simple retrieval tool. No further behavioral details are needed.

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; first states the resource and its contents, second gives usage context and alternative. No wasted words.

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

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

Given no parameters, no output schema, and a simple read operation, the description fully covers what the agent needs: what it returns, why to use it, and when to use the sibling instead.

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 zero parameters at 100% coverage, baseline is 4. The description adds no parameter info because none exist.

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

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

The description clearly states it retrieves the Designesy /llms.txt brief and lists its contents. It distinguishes itself from the sibling tool designesy_llms_full_txt by noting the alternative for a fuller brief.

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

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

Explicitly recommends using it for fast, low-token orientation before heavier artifacts, and directs to the full brief using designesy_llms_full_txt when needed. Also states it is read-only.

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 no annotations, the description fully covers behavioral traits: it parses and validates server-side, specifies required fields (v, fr, ip, op, w, h, layers, $version, markers array, no deprecated version), and explains both input methods (URL or raw JSON). No contradictions.

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

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

The description is front-loaded with the core purpose and includes necessary details without redundancy. It is slightly dense with specific terms (m01-m10, required fields) but remains clear and efficient.

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

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

The description explains return format (10 checks with PASS/FAIL/WARN), input methods, required fields, and provenance. Without an output schema, it provides sufficient context for the agent to understand what the tool returns.

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

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

Schema description coverage is 100% with clear param descriptions. The tool description adds context about input alternatives (URL vs. raw JSON) but does not significantly augment beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool validates a Lottie animation file against specific standards (Lottie spec v1.0.1 and Designesy motion standards), returning 10 checks with PASS/FAIL/WARN. It distinguishes from sibling tools like designesy_score.

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 specifies when to use (verify well-formed and accessible motion asset) and explicitly mentions an alternative (designesy_score for full-site score). It does not explicitly state when not to use, but the alternative provides 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?

With no annotations, the description fully discloses behavior: fetches HTML, extracts CSS, parses custom properties, runs checks server-side, returns JSON with score/grade and per-check details, and notes that checks needing a live browser are marked SKIP. Also mentions version coverage.

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

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

The description is well-structured, front-loading the purpose and key functionality. It's concise but includes relevant details about checks, version coverage, and alternatives. Slightly verbose in listing technical details, but effective.

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 one parameter and no output schema, the description covers input behavior, execution, return value (JSON with score/grade/per-check), limitations (skip checks), and provides a sibling alternative. It is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description confirms the default URL and behavior but does not add additional semantic value 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 clearly states the tool's purpose: scoring a live URL against a design contract with a deterministic 34-check engine. It uses specific verb 'score', resource 'live URL', and distinguishes from sibling 'designesy_design_review' by noting it's for compliance scoring, not qualitative critique.

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

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

Explicitly states when to use: 'audit whether a website or AI-generated UI complies with a real design contract.' Also provides an alternative: 'For qualitative design critique rather than compliance scoring, use designesy_design_review.' No exclusions needed.

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?

States 'Read-only' and 'Returns markdown text', covering key behavioral traits. Could mention that no side effects occur, but the zero-parameter read operation is sufficiently disclosed. No annotations provided, so description carries full burden.

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 concise sentences, front-loaded with purpose, no redundancy. Every sentence adds value regarding content, usage, and alternatives.

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 zero parameters and no output schema, the description fully covers the tool's purpose, usage, return type, and relationships to sibling tools.

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

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

No parameters exist (schema coverage 100% trivially), so baseline is 4. Description does not need to add parameter 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?

Description clearly states 'Get the Designesy SKILL.md' and explains its content as 'agent-skill-format export of the design-system contract'. It distinguishes from siblings by explicitly naming designesy_contract and designesy_score as alternatives for different needs.

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

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

Explicitly states when to use: 'when you want the contract in a form that steers how an agent builds UI' and specifies compatibility with Cursor/Claude Code/Replit. Provides clear alternatives for raw JSON (designesy_contract) and scoring (designesy_score).

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

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

With no annotations provided, the description compensates by disclosing that the tool is executable (server-side), lists the conformance checks (t01-t10 with PASS/FAIL/WARN), and mentions provenance. It does not describe side effects or authorization needs, which are minimal for a read-only validation tool.

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

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

The description is a single dense paragraph, front-loaded with the primary purpose. It packs details on checks, parameters, execution model, and provenance without extra fluff. Slightly longer than necessary but still focused.

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 covers outputs by listing the 10 conformance checks and what they verify. It adequately informs about inputs (url or dtcg_file) and the validation scope. Missing details about response format beyond pass/fail/warn, but sufficient for a validation tool.

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

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

Schema coverage is 100% (both parameters described). The description adds little beyond the schema: it repeats the parameter names and mentions fetching behavior for 'url' and that 'dtcg_file' is an alternative. This provides marginal additional context.

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

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

The description clearly states the tool validates a design token file against the W3C DTCG format, returning 10 checks. It uses specific verbs ('validate', 'returning') and resources ('design token file', 'W3C DTCG format'), and distinguishes from the sibling tool 'designesy_score' by noting it is for whole-site scoring.

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 advises using this tool to verify token file structure and contrasts with 'designesy_score' for site scoring. However, it does not provide when-not-to-use guidance or mention other sibling alternatives.

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