Tap

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

Annotations declare readOnlyHint=false and openWorldHint=true, implying mutation and external access. The description confirms live verification when url is provided and mentions returning {score, rows}. However, it does not disclose side effects like memory consumption, potential overwrites, or access requirements beyond what annotations hint. The description adds some value but lacks depth for a tool that modifies state.

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, starting with a clear action-oriented purpose. All critical information (input modes, behavior modes) is included without redundancy. Every phrase adds value, making it highly 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?

Given 5 parameters (none required), no output schema, and complex two-mode behavior, the description covers the main scenarios: with url (verification) and without (stashing). It explains the two input options and their relationship. However, it could be more complete by clarifying what 'stashes the draft' means in terms of state persistence or lifetime.

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 has 100% coverage; each parameter is described. The description adds context about the preferred usage of plan over code and explains the url behavior. However, it does not significantly enhance understanding beyond the schema, and the parameter 'description' is mentioned without additional semantic value. 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 loads a tap into memory and optionally verifies it live. It specifies two input modes (plan and code) and differentiates behavior based on url presence. However, it does not explicitly differentiate from sibling tools like tap_run or tap_list, leaving some ambiguity about when to use this tool over others.

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

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

The description provides explicit guidance on when to use url (auto-run verification) and when not (stash draft). It also indicates a preference for the plan parameter over legacy code. While it doesn't explicitly mention alternatives or when-not-to-use, the context of the tool (loading draft) is reasonably clear from the description.

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 are readOnlyHint=true, destructiveHint=false, openWorldHint=true. Description adds detail that probe_writes has zero side effects and emphasizes discovery without execution. No contradictions, and description complements annotations well.

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, starting with the primary purpose, then secondary use, parameter tip, and authoring principle. It is front-loaded and informative, though slightly lengthy. Still earns a 4.

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 purpose (analysis), the description covers main outputs, parameter usage, and authoring principles. No output schema, but the description mentions default return values. Adequate for the 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 67% (probe_writes and detail have descriptions; url does not). The description adds context for probe_writes and detail, but does not significantly extend beyond what the schema provides for those parameters. 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 analyzes pages for tap forging, detects framework/SSR/APIs, and generates extraction strategies. It also distinguishes between initial analysis and re-forging broken taps, making the purpose specific and 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 provides explicit guidance on when to re-forge (broken taps) and how to use probe_writes. It mentions reading existing_taps first, but does not fully distinguish this tool from all siblings like inspect, though context implies it's for page analysis.

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 indicate destructive hint (true), and description elaborates: 'auto-commit to git', 'migrated to a plan on write', and post-save execution capability. Describes conditional behavior with verify_examples: on success returns doctor, on failure returns regenerated_inspect. No contradiction with annotations.

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?

Description is front-loaded with core action, then modes, then verification details. Each sentence adds value. Slightly lengthy due to detailed verify_examples explanation, but that is necessary for completeness. Could be trimmed slightly without losing clarity.

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 covers return values thoroughly: doctor on success, regenerated_inspect on failure, and default indeterminate. Explains fallback behavior and migration. Covers all aspects of the tool's behavior, making it self-contained for agent 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?

Schema coverage is 60%, and description adds meaning for plan, code, and verify_examples with usage details. Site and name are not elaborated in description but are straightforward required identifiers. The explanation of verify_examples' sub-fields (min_rows, non_empty, max_elapsed_ms) compensates for nested complexity. Could describe site/name more, but adequate.

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's purpose: saving a tap to disk as .tap.json with auto-commit to git. Distinguishes from siblings like forge_draft (which presumably creates drafts) and forge_inspect (which inspects) by focusing on persistence. Mentions two input modes (plan preferred, code legacy) and fallback to draft session.

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 each parameter: 'plan (W3C Annotation...preferred)' vs 'code (legacy .tap.js source...)', and fallback to active forge.draft session. Also explains when to use verify_examples and its outcomes, enabling the agent to make informed decisions about error handling and round-trip optimization.

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 indicate read-only and non-destructive behavior. The description adds useful behavioral detail for the 'network' target, specifying auto-start and dump behavior. 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 two concise sentences with front-loaded purpose. Every part adds value, 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?

The description covers main targets and network behavior, but lacks details on output format. Given no output schema, this is a minor gap. Overall, it provides a solid understanding for an 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 covers all parameters with descriptions. The tool description adds extra meaning by summarizing what each target inspects and noting that 'element' requires a selector, enhancing understanding 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 tool inspects the current page and lists target options. However, it does not differentiate from the sibling tool 'forge_inspect', which may serve a similar purpose.

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 for each target option and explains default behavior. It does not explicitly state when not to use the tool or mention alternatives, but the guidance for target selection is sufficient.

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, openWorldHint, and destructiveHint. Description adds rich behavioral context: return format with W3C Web Annotations, verdicts, and recursive sub-tap diagnosis for pipe taps via body.children[]. It also warns about expensive unscoped scans. No contradiction with annotations.

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 but packs information: purpose, return format, usage guidance, caveat, and pipe-specific behavior. Each sentence adds value. Could be slightly more structured but is 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?

Despite no output schema, the description fully details the return structure including the annotation format and verdicts. It covers pipe taps with recursive diagnosis. It also references a sibling (tap.explain) for static analysis. Given the tool's complexity, the description is complete.

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 descriptions for all 3 parameters. Description adds meaningful context beyond schema: reinforces that site and name should always be specified, and explains that omitting them scans all user taps (expensive). This adds value over the bare 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's purpose: 'Health check for taps. Runs each tap's examples against its health contract. Returns {ok, annotations[], issues[], suggestions[]}.' It gives specific return structure and verdicts. It distinguishes from siblings like tap_run (runs the tap) and tap_explain (static analysis).

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

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

Explicitly states when to use: 'Use when tap.run returns empty/error rows, or after forge.save to validate.' Also gives a strong caveat: 'ALWAYS specify site+name — unscoped checks scan all user taps and are expensive.' Provides an alternative: 'Use tap.explain for static analysis without running.'

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 provide safety hints (readOnlyHint, destructiveHint, idempotentHint). The description adds 'Zero side effects — no browser needed,' reinforcing and adding context beyond annotations.

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 main purpose, then usage guidance. No redundant or 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?

Given no parameters, no output schema, but rich annotations, the description is complete: it explains what the tool checks and when to use it. No missing 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 exist, and schema coverage is 100% (trivial). Per guidelines, 0 parameters 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?

The description clearly states the tool checks tap runtime environment, listing specific items (binary version, TAP_HOME, skills count, etc.) and explicitly distinguishes from siblings by noting zero side effects and no browser needed.

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 says 'Use for initial troubleshooting or CI health gates,' providing clear context. While it doesn't explicitly mention when not to use or alternative tools, the purpose is well-defined among 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?

The description fully discloses the behavioral impact: after calling, the server sends notifications/tools/list_changed, and clients that honor it will re-query tools/list automatically. This explains the dynamic nature of the tool set expansion. The annotation 'openWorldHint: true' aligns with the description, confirming that the tool can change available tools. There is no contradiction.

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 is generally concise and front-loaded with the main action. Every sentence adds value, but it could be slightly more streamlined. For example, the list of level-3 tools is helpful but somewhat lengthy. Overall, it is well-structured and informative without being verbose.

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 tool with only one parameter, no output schema, and complex behavior (expanding the tool set with side effects), the description covers all essential aspects: purpose, when to use, level details, server notification, and client behavior. It is complete enough for an agent to decide correctly whether and how to invoke this 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?

Although the schema provides an enum for the 'level' parameter with values 2 and 3, the description adds significant meaning by explaining that level 2 is 'creative (forge supplements + diagnostics)' and level 3 is 'manual (raw browser control: tap.click, tap.type, etc.)'. It also clarifies that higher-level calls subsume lower ones, which is not evident from the schema alone. With 100% schema coverage, the description goes beyond the baseline 3.

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: to expand the MCP tool set. It specifies the context when the default Layer-1 set is insufficient, and explicitly lists the types of operations (e.g., browser actions, write-tap operations, diagnostics) that warrant its use. This distinguishes it from sibling tools like 'tap_run' or 'inspect' by focusing on tool set expansion rather than individual tool execution.

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

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

The description provides explicit guidance on when to use the tool ('when default Layer-1 set is insufficient') and gives concrete examples of needed actions. It explains the two levels (2 and 3) and what each exposes, including the condition that higher levels subsume lower ones. The description also notes the side effect of server notification and client re-query, which helps agents understand the invocation 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?

Annotations indicate readOnlyHint=true, but the description says 'repair' which implies mutation, creating a contradiction. The description also does not clarify whether the repair is actually applied or just proposed. This lack of clarity is problematic.

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 very concise: four sentences, no wasted words. The first sentence states purpose, front-loading key information. Structure is 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 the process and return shape partially, but given no output schema, it should provide more detail on the structure of diagnostics and patches. It also omits what 'repair' actually does, which is critical given the annotation contradiction.

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 context about the process (runs tap.doctor) and return shape but does not provide additional meaning for individual parameters like name, site, or timeout beyond what the schema already gives.

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 verb ('diagnose and repair') and resource ('broken tap'), and distinguishes from sibling tool tap_doctor by indicating it builds on 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 says 'Use when tap.doctor returns verdict=broken.' This tells when to use. It also mentions tier differences (free vs Pro) affecting capabilities. Missing explicit when-not-to-use or alternatives, but the guidance 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?

Annotations already indicate readOnly, idempotent, non-destructive. Description adds behavioral context: default returns compact site-grouped summary, query returns flat ranked results, site/name returns full schema.

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?

Description is fairly concise given the complexity of three modes. Front-loaded with main purpose. Some redundancy in explaining when to use tap_run 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?

Despite no output schema, the description covers return formats for each mode (compact summary, full schema columns/args, flat ranked). Includes examples and usage guidance, making it complete for an 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%. Description adds meaning beyond schema for each parameter: name requires site, query is for substring search with ranking, site filters and returns 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 discovers available taps and explains three distinct modes (default summary, query search, site/name schema). It distinguishes itself from sibling tools like tap_run which executes taps.

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 advises when to use each argument pattern: default for orientation, query for search, site/name for schema. Also warns against bypassing with manual tap calls and recommends tap_run for existing taps.

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 adds significant behavioral context beyond annotations: read-intent taps are memoized for 5 minutes, identical calls return cached data with cache_hit:true, fresh:true bypasses cache, write-intent taps never cache, and error handling for login/error pages and transient failures. Annotations are readOnlyHint=false, destructiveHint=false, openWorldHint=true, and description does not contradict them.

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

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

The description is appropriately sized, front-loads the core purpose, and every sentence serves a purpose: stating purpose, caching behavior, error handling, and retry logic. No redundant content.

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 5 parameters, full schema coverage, sibling tools, and absence of output schema, the description covers return shape ({columns, rows, count, timing, cache_hit}), caching behavior, error recovery mechanisms, and when to use sibling tools. It is complete and self-contained.

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 fresh:true bypasses cache, envelope parameter differences between 'bare' and 'annotation', and implicit context for site and name. While schema already describes parameters, the description clarifies their behavioral impact.

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 runs a pre-built tap, emphasizes it is preferred over tap.* tools, and distinguishes sibling tools by highlighting deterministic behavior with zero AI at runtime.

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 usage guidance: when to use this tool, when to use fresh:true to bypass cache, when to fall back to tap.runtime for login/error pages, when to use tap.doctor for empty rows on public sites, and how to handle transient failures by retrying tap.run. It also specifies caching rules and 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?

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds behavioral context: switching runtime affects login availability (chrome provides user sessions, headless does not). No contradictions with annotations.

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 purpose, highly concise with no wasted words. Clearly structured and easy to parse.

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 runtime switch tool with no output schema, the description covers behavior, usage scenarios, and distinguishes from unrelated commands. No 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 single parameter has a clear enum and schema description. The tool description adds value by contextualizing when to use each value (chrome for login, headless otherwise), going 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 tool's purpose: 'Switch browser runtime mid-session.' It specifies the two runtime options (chrome and headless) and what each is used for, making the action 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 explicitly advises when to use each runtime: chrome for login sessions or write operations, headless to switch back. It also distinguishes from `tap mcp connect`, providing clear usage context.

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