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

With no annotations, the description adequately discloses key behaviors: unanswered fields get researched defaults and the assumption ledger is auditable and reversible. This covers the main side effects of the 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?

Two sentences, no wasted words. The action and key details are front-loaded, making it easy to understand.

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 low complexity (2 parameters, no output schema) and the presence of sibling tools, the description is complete. It explains the core functionality and side effects, leaving no significant gaps.

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% coverage, and the description adds value by specifying that 'prompt' should be the same as in brief_start, and 'answers' expects question IDs to answers with instruction to omit unknowns. This greatly clarifies usage.

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 'Submit brief answers' as a verb+resource pair. It further explains that unanswered fields are handled with researched defaults and recorded in an assumption ledger, which distinguishes it from sibling tools like brief_start.

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 on when to use the tool (after brief_start, when submitting answers) and what happens with omissions (defaults, ledger). It lacks explicit when-not-to-use or alternatives, but the guidance is sufficient for an agent.

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 must fully explain behavior. It describes returning a questionnaire and instructs the agent on how to handle questions, but does not discuss side effects, idempotency, or permissions.

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 with three sentences. It front-loads the purpose and then provides actionable instructions. No unnecessary 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?

The description lacks details about the return format of the questionnaire, which is important for an agent deciding whether to call this tool. It covers the workflow but omits output 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?

Schema coverage is 100%. The description adds value by explaining how to use the 'context' parameter to extract answers, which goes beyond the schema's 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 'Start a design brief' with a specific verb and resource. It distinguishes from the sibling tool 'brief_answer' by indicating this initiates the process, and the agent should then call brief_answer.

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: answer questions from context, relay only askHuman questions to user, then call brief_answer. It does not specify when not to use it, but the workflow 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?

With no annotations provided, the description carries the full disclosure burden. It thoroughly details the exact contents of the returned packet (comment, layout block, screen definition, journey states, transitions, validation findings), giving the agent a clear behavioral contract. It implies a read-only operation for gathering context, though it doesn't explicitly state side-effect absence.

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 sentence that front-loads the key purpose ('The full work packet for one reviewer comment') and then itemizes contents in a structured list. It is efficient and free of fluff, though slightly dense due to the enumeration length.

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 output schema, so the description fully enumerates the return payload (comment, layout block, screen definition, journey states, transitions, validation findings), leaving no ambiguity about what the agent will receive. It also ties the usage into the resolution workflow, making it complete for a complex context-gathering 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 only parameter 'id' has complete schema coverage with the description 'Comment id from comments_list'. The tool description adds no param-specific semantics beyond this, so the baseline of 3 applies for high 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 clearly states the tool returns 'the full work packet for one reviewer comment' and enumerates its contents with specific resources (comment, layout block, screen definition, journey states, validation findings). It distinguishes itself from siblings like comment_resolve and comments_list by positioning itself as the detailed context provider before resolution.

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 it to address the comment precisely, then call comment_resolve,' which gives a clear directive on when to use the tool relative to comment_resolve. It does not list exclusions or alternatives, but the workflow context 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?

With no annotations present, the description carries the transparency burden and succeeds: it discloses that the resolution note is shown to the reviewer, is persisted, and clears the pin live in all open previews. These are concrete, observable effects beyond merely stating 'resolve'.

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; the first states the action and precondition, the second adds behavioral consequences and a safety rule. 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 simple two-parameter mutation with no output schema, the description provides purpose, precondition, behavioral effects, and a caution. All necessary operational context is present.

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?

Input schema already covers both parameters at 100%, so baseline is 3; the description adds value by explaining that the 'resolution' value is surfaced to the reviewer and persisted, which clarifies the stakes of that parameter. However, it doesn't describe id formatting or any additional constraints 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?

Description opens with 'Resolve a reviewer comment after addressing it' – a specific verb and target resource that clearly distinguishes it from sibling read/lookup tools like comments_list and comment_context. The phrase 'after addressing it' adds necessary context about the action's precondition.

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 timing ('after addressing it') and an explicit prohibition ('Never resolve without actually making the change'), which covers both when and when-not to invoke this tool. While no alternative tool is named, the strong operational guardrail clearly differentiates the intended use case from comment listing/context 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?

With no annotations, the description carries the transparency burden. It explains the lifecycle statuses, what 'assigned' means ('→ agent' clicks), that they are the work queue, and the default behavior of showing unresolved comments. It doesn't fully describe return format or pagination, but for a simple list tool this is sufficient 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 three sentences, each earning its place: purpose, workflow, and when to use. It is front-loaded with the core function, then provides actionable details without 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 tool's simplicity (one optional param, no output schema), the description is nearly complete. It explains what the tool does, how to process the results, and when to check. It doesn't enumerate the exact fields returned, but the workflow guidance offsets that 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 description covers the parameter 100%, so baseline is 3. The description adds semantic meaning beyond the schema by defining 'assigned' as comments the reviewer clicked '→ agent' on and explicitly stating the default behavior (unresolved = open + assigned, assigned first). This gives the agent deeper understanding of the enums.

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 lists reviewer comments with lifecycle status, using a specific verb and resource. It distinguishes itself from sibling tools by framing the list as the work queue for assigned/open comments and explicitly names comment_context and comment_resolve as follow-on actions.

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 guidance: check at session start and after every validation run. It also lays out the full workflow (call comment_context, make change, comment_resolve) and indicates which comments to prioritize (assigned first), making it easy for the agent to decide when to invoke this tool.

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 discloses that the tool returns per-screen coverage and a missing-state list, implying a read-only operation. However, with no annotations provided, it does not cover details like data sources, required permissions, or potential performance impact.

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 wasted words. The first sentence states the purpose, the second explains the output. Highly concise and 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?

The description is adequate for a simple reporting tool with no parameters, but it lacks context relative to the sibling 'project_validate'. No output schema is provided, but the return values are mentioned. Complete enough for basic 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?

The input schema has zero parameters, so schema description coverage is 100%. The description adds no parameter info because none exist, which is acceptable. Baseline score for zero-parameter tools is 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 clearly states the tool compares screens delivered vs. states needed and returns per-screen coverage and missing-state list. It distinguishes from sibling 'project_validate' by focusing on coverage, but lacks a specific verb like 'calculate' or 'generate'.

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?

No guidance on when to use this tool versus the sibling 'project_validate'. The description does not mention prerequisites, alternatives, or 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the tool is deterministic, has zero coupling, and does not use the Figma/Penpot API. However, it does not explicitly confirm that the audit is read-only with respect to the input design files, though the optional scaffold write is disclosed. This is a minor gap.

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 well-organized, front-loading the core purpose and then adding details about inputs, outputs, and optional behavior. It avoids fluff but includes jargon such as 'Reverse bridge (RFC 0007)' which may not be immediately clear to all agents. Overall, it is appropriately concise for the tool's complexity.

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 there is no output schema, the description does a good job of explaining what the tool reports (specific error codes) and the optional scaffold output. It could be more explicit about the exact return format, but the description provides sufficient detail for basic usage. The tool's complexity is moderate, and the description covers the key aspects.

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 descriptions for both parameters (design and scaffold), covering 100% of them. The description adds extra meaning by explaining what kinds of paths design accepts (file, folder, manifest) and clarifying the scaffold's purpose as writing a draft screens fragment. This goes beyond the schema's minimal descriptions, providing valuable 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 opens with 'audit a design export against the contract', a specific verb+resource statement. It further clarifies the scope by listing acceptable inputs (Figma/Penpot SVG/JSON export, folder, manifest) and the error codes it reports, clearly distinguishing it from generic audit tools. While it doesn't name sibling tools, the specific inputs and output codes make its 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 implies the tool is for analyzing design exports against a contract, but it does not explicitly state when to use it over alternatives like coverage_report or project_audit. It provides clear context for the design parameter (file, folder, or manifest) and describes the optional scaffold behavior, but no exclusions or alternative tool references are present.

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 the full burden and does so thoroughly. It discloses the enforced max-round limit, persistence with deltas to a specific file, the computed metrics, and the refusal behavior for round 4. This exceeds typical transparency 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?

The description is concise and front-loaded, starting with the core purpose in the first sentence. Every sentence contributes essential context: enforcement, computation, persistence, return value, and iterative usage. No word is wasted.

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 lacking an output schema, the description fully explains the return value (a structured rubric with six specific criteria), the persistence behavior, the round limit, and the recommended user action on refusal. This makes the tool's operation completely understood.

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 single parameter 'notes' is already fully described in the schema as 'What this round focused on / what changed since the last round'. The description adds no further parameter-specific detail beyond the schema, so the baseline of 3 applies due to 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 clearly identifies the tool as an iterative design-review round with specific actions: computing validation and rationale coverage, persisting to reviews.json, and returning a structured rubric. It distinguishes itself from siblings by naming the enforcement limit (max 3) and the rubric criteria, making its function 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?

It explicitly describes the iterative workflow: 'Address the rubric, improve the design, then call again' and instructs that round 4 should be refused and results presented to the user. This is strong contextual guidance, though it does not explicitly compare to alternative tools like screen_critique or design_audit.

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 the add-or-replace behavior and the dependency on screen_register/project_validate, which is useful. However, it does not mention potential side effects of replacing a journey, error conditions, or what response to expect, leaving some critical behaviors unspecified.

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-loaded with the action phrase, and no filler. The parenthetical efficiently explains the domain concept, and the second sentence directly states a critical dependency. Every word 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?

The tool is complex with nested objects, and the description provides the essential mental model (state machine, screen registration order). It wisely leaves detailed parameter shapes to the rich schema, so the agent has enough to select and use the tool correctly, though it omits details about return values or validation 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 provides detailed structure and has 100% coverage with a brief 'journey definition' description, but the tool description enriches this by explaining that states reference screens and events move between states. This adds domain semantics beyond the raw schema, helping the agent understand how to construct the journey object.

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: 'Add or replace a journey'. It further clarifies the concept as 'a state machine' with states and events, which distinguishes it from sibling tools like screen_register that handle screens. This precisely states what the tool does.

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 a prerequisite for using this tool: screens must be registered via screen_register before project_validate passes. This implicitly tells when to use this tool (after screen registration) and relates it to other tools, though it does not explicitly explain 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?

With no annotations, the description carries the full burden. It discloses WCAG version, threshold, and output details (ratio, pass/fail, thin-margin alerts). It is implied to be read-only with no side effects, though not explicitly 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 two sentences with no wasted words. It is front-loaded with the main action and threshold, then details output specifics.

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 adequately covers purpose, output, and a key constraint (before screens). For a tool with one parameter and no output schema, it is nearly complete, though it could mention that only hex colors are accepted (already in schema).

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%, so the description must add parameter meaning. However, it only discusses output; it does not explain input structure beyond what the schema already defines (hex patterns, name field). The description does not compensate for the coverage gap.

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 checks color pairs against WCAG 2.2 AA (4.5:1) and reports exact ratio, pass/fail, and thin-margin passes. It specifies an early design use case ('before any screens exist'), distinguishing it from any potential screen-related 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 use during design pre-implementation ('before any screens exist') and differentiates from screen_critique by focus on raw color pairs. However, it does not explicitly state when not to use or mention alternatives, though no closely related siblings exist.

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 explains the tool is a read-only audit that returns verdicts and findings, and advises on marker emission. It does not disclose any destructive behavior; the tool appears non-modifying. Transparency is good but could be more explicit about side effects.

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 reasonably concise with two sentences, but the first sentence is lengthy with internal lists. It is well-structured: purpose, method, returns, and guidance. Minor verbosity does not detract significantly.

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 simple input (one optional parameter), no output schema, and no annotations, the description fully covers the tool's purpose, inputs, outputs (verdicts with evidence and findings with fixes), and usage advice. No gaps are evident.

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 sole parameter 'root' is fully described in the schema (100% coverage). The description does not add meaning beyond what the schema already provides, so 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 audits implementation against design contract for drift detection, specifies the static tiers (screen registry and markers), and describes return values. It distinguishes itself from sibling tools like project_init or screen_critique by focusing on compliance verification.

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 guidance on when to use the tool: when implementing screens from the contract, emit markers to keep code self-auditing. It also implies usage for drift detection but does not explicitly state when not to use it or provide alternatives, though sibling tools offer context.

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 the full burden. It states the tool returns the document, implying a read-only operation, but does not explicitly disclose non-destructiveness, permissions, or other behavioral traits. Adequate but could be more explicit.

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 wasted words. It efficiently conveys the tool's action and rationale.

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 adequately covers the tool's function and use cases. It could mention potential size limits or errors, but the simplicity of the tool makes this 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?

There are zero parameters, so the schema coverage is 100% and the description adds minimal parameter-specific value. Baseline of 4 is appropriate as the description doesn't need to compensate.

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 returns the complete current project document, specifying use cases (inspection, backup, transformation) and directly referencing the sibling project_import, making its purpose and differentiation clear.

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 context for use (inspection, backup, transformation before import) and implicitly distinguishes from siblings like project_import, but does not explicitly state when not to use the tool or provide a full set 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?

Since no annotations are provided, the description carries the full burden of disclosing behavior. It reveals that the tool is a replacement operation ('Replace the whole project') and that it 'validates the full document' with 'unknown fields rejected.' However, it does not mention what happens after successful validation (e.g., whether the save is immediate or if there is a return value), which would be useful.

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 concise sentences. The first sentence states the primary action and scope, while the second provides usage guidance and validation behavior. Every word adds value, with no redundancy or 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 complex tool with a large nested schema and no output schema, the description provides essential context: what it does, when to use it, and key validation behavior. It also differentiates it from sibling tools. Missing details such as return value or explicit 'when not to use' are minor given the clarity of the overall message.

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 single parameter 'project' is already described in the schema as 'The complete JourneyGraph project document,' giving 100% schema description coverage. The tool description adds that it includes 'journeys and screens together' and that 'unknown fields are rejected,' but these are more about behavior and scope than about parameter meaning. With full schema coverage, the baseline 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 clearly states the tool's core action: 'Replace the whole project in one call: journeys and screens together.' This identifies the specific verb (replace), the resource (project), and the scope (journeys and screens). It also distinguishes itself from sibling tools by explicitly contrasting with 'many journey_define/screen_register calls'.

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 usage guidance: 'Prefer this over many journey_define/screen_register calls when registering a complete or large design.' This provides a clear condition (complete/large design) and names alternatives, making it easy for an agent to decide when to use this tool instead of the incremental ones.

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, so description must fully disclose behavior. It states the tool creates a file but omits whether it overwrites an existing file, error behavior on repeated runs, permissions needed, or other side effects. Minimal transparency for a state-changing 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?

Two short sentences convey the core purpose and a critical constraint with zero waste. Information is front-loaded and every word 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?

While the description covers basic purpose and a usage constraint, it lacks details on return values, prerequisites (e.g., directory context), and how this tool relates to siblings. With a simple interface and no output schema, more context would improve 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% with clear descriptions for both parameters. The tool description adds no additional semantic meaning beyond what the schema already provides, meeting the baseline but not exceeding it.

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?

Clearly states the tool creates a new UXLoom project file with the specific filename 'uxloom.project.json'. The constraint 'Run once per product' distinguishes it from sibling project tools like project_audit or project_export.

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 includes the important guideline 'Run once per product', implying one-time initialization. However, it lacks explicit when-to-use vs alternatives or prerequisites, leaving some inference to the agent.

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 the burden of behavioral disclosure. It does explain what the tool checks and that it honors thresholds, but it never clarifies whether the tool is read-only or may mutate state. The phrase 'Iterate until errors = 0' is ambiguous— it could be an instruction to the agent rather than a tool 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 front-loaded with purpose and a bullet-like enumeration of checks. It is packed with useful specifics and contains no fluff, though the list is a bit of a run-on.

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 annotations and no output schema, the description does a good job of covering what the tool does, what it honors (thresholds), and the expected usage loop. It could mention return format more explicitly, but the error-count reference implies the output.

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 baseline is 4. The description adds meaningful context about what the validation covers, though no parameter-specific guidance 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 'Run every critic,' which clearly establishes a comprehensive validation action. It enumerates specific checks (journey completeness, WCAG contrast, touch targets, etc.), distinguishing it from narrower siblings like screen_critique or coverage_report.

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 is implied: this is the go-to tool for full project validation, with an iterative loop until errors are zero and reviewer comments are resolved. However, it does not explicitly state when to use it versus alternatives or 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?

No annotations are provided, so the description must fully disclose behavioral traits. It only states the tool is scoped to a screen but does not mention whether it is read-only, what happens on invalid screenId, or any limits. This is insufficient.

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 extremely concise with two short sentences, front-loading the key purpose. No unnecessary 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?

For a simple single-parameter tool with no output schema, the description provides minimal but adequate context for basic usage. However, it omits details like return format and error behavior, leaving gaps 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?

The single parameter screenId has 0% schema description coverage, and the description adds no semantics about it (e.g., format, how to obtain, default behavior). The description does not compensate for the missing schema 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 returns findings scoped to a single screen, distinguishing it from broader siblings like coverage_report or project_audit. The verb 'scoped' is slightly passive but sufficient.

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 advises using during iteration on one screen, implying when to use but does not explicitly state when not to use or mention alternatives. The sibling tool list provides context but is not referenced.

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 must disclose behavioral traits. It mentions 'add or replace' but does not explain what replace does to existing data, whether it is idempotent, any validation side effects, or return values. The behavioral implications are largely opaque.

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 sentence that is front-loaded with the primary action and efficiently lists key components without filler. It is concise and well-structured.

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 a highly complex nested schema, and the description provides only a partial overview. It covers the required fields and components, but omits the required 'id' and other important optional properties. It gives enough context for a high-level understanding but relies heavily on the schema for full 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?

The schema's only parameter 'screen' has a generic description ('The screen definition'), so the tool description adds some meaning by listing fields like intent, requiredStates, and designedStates. However, it omits many other properties (layout, rationale, exemptions) and does not fully clarify the parameter's structure 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 'Add or replace a screen' with a specific object, and enumerates key fields (intent, requiredStates, designedStates, components). However, it does not explicitly distinguish this tool from siblings like screen_critique, so it misses full differentiation.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, contexts, or exclusions. The only implied usage is the basic action of adding or replacing a screen, which is just the purpose restated.

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