audit_interface_craft

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

No annotations are provided, so the description must fully disclose behavioral traits. It states the tool audits interface craft and returns a JSON report, implying a read-only analysis. It does not mention side effects, required permissions, performance characteristics, or limitations. The description adds some context (e.g., use cases) but lacks details on whether it modifies anything, rate limits, or prerequisites.

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

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

The description is two sentences long. The first sentence succinctly states the core function. The second sentence efficiently communicates the return type, usage scenarios, and companion tools. No unnecessary words or repetition. Perfectly front-loaded and compact.

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 (3 parameters, no output schema), the description provides sufficient context: input sources, return structure (score, critique, dimensions, findings, topOpportunities), and usage guidance. It mentions partner tools for additional context. The only gap is the lack of behavioral details, but the description covers the essential decision-making information for an AI 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 baseline is 3. The description adds value beyond the schema by explaining that 'target' defaults to the current project root and that maxFiles is used 'when target evidence is used.' It also clarifies that screenshotPath is optional and intended to 'attach to the craft audit.' This extra context justifies a score above 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 description clearly states the tool's function: 'Audit interface design craft from local app-quality evidence or a screenshot artifact.' It specifies the resource (interface design craft), the action (audit), and the input sources (local evidence or screenshot). The mention of the return type (InterfaceCraftReport JSON) and specific sub-dimensions further clarifies purpose. It also distinguishes from sibling tools by naming partners (diagnose_app_quality, audit_ux_tenets_traps).

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 recommends when to use the tool: 'Use before UI edits or after a redesign; pairs with diagnose_app_quality and audit_ux_tenets_traps.' This provides clear context and partnering tools. However, it does not mention when not to use it or contrast with alternatives like 'run_audit' or 'plan_ui_fixes,' which would elevate it to a 5.

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