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

Returns specific fields and is read-only. No annotations, but the description explains output and usage. Could mention external call but not required.

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, efficient: first states purpose and output, second gives usage guidance. 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?

Complete for a simple status tool: describes action, return fields, and when to use. No output schema but description covers it.

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; schema coverage 100%. Description adds meaning by specifying return fields and usage, meeting baseline for 0 parameters.

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 it reports bridge version and checks for updates on npm. Names the return fields and describes the action with specific verb and resource.

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 to call when user asks if updates exist or proactively when tools fail due to stale bridge. Provides clear 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 of behavioral disclosure. It reveals the return shape ({status, headers, body}), default localhost-only scope, and the rarity of allow_remote. However, it could mention rate limits or permissions for making external requests, but the explicit security constraint (localhost default) compensates, making it mostly 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?

The description is a single, well-structured paragraph of 4 sentences. It front-loads the main action (HTTP request) and follows with specific use cases and constraints. Every sentence adds value without redundancy, making it concise and easily scannable.

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 or annotations, the description covers all necessary aspects: return format, typical use cases, security scope, and limitation (not general-purpose). It is sufficient for an agent to understand and correctly invoke the tool, addressing the complexity of making an HTTP request.

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 has 0% property descriptions, so the description must compensate. It provides meaning for url (example localhost URLs), method (implicit via enum), and allow_remote (rare). Headers and body are not elaborated beyond the schema, but the overall context of making an HTTP request gives them implicit meaning. The description adds value but does not fully detail all parameters.

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 function: making an HTTP request and returning status, headers, body. It distinguishes itself from sibling tools like mock_endpoint or peek_openapi by providing specific use cases (testing mocks, inspecting admin API, verifying endpoints). This satisfies the specific verb+resource requirement and differentiates from alternatives.

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 outlines when to use the tool (demonstrate a mock, inspect admin API, verify mock endpoint) and when not to (the bridge is not a general-purpose HTTP client, allow_remote is rare). This provides clear context and exclusions, guiding the agent to appropriate usage.

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?

Discloses search paths and response content (install_options), though does not detail whether it executes the CLI or just checks files.

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?

Concise and structured, though slightly verbose with user guidance that could be secondary.

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?

Covers key aspects: inputs (none), actions, and follow-up steps. No output schema, but description implies response 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?

No parameters; baseline 4 applies. Description adds no parameter info but none 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 clearly states the tool checks CLI availability across three specific locations, and distinguishes its use case as the first step for local mockzilla attempts.

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 'Call FIRST' and provides follow-up action: if unavailable, suggest install_cli with method options.

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, and it succeeds: it explicitly states the tool is read-only and never changes the repository, describes the shape of the return value (problems, warnings, workflow_to_add), and gives concrete examples of warnings such as missing teardown triggers and 128MB simulation limits.

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: purpose first, usage second, then return behavior. Every sentence adds useful information, with no filler or 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 two self-documenting parameters and no output schema, the description adequately covers what the tool does, when to use it, what it returns, and its safety profile. An agent can decide to invoke it and interpret its results correctly.

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 schema already fully documents both parameters. The description adds no new parameter-level meaning beyond referring to repos and local folders, matching the schema. 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 states a specific verb and resource: it says whether a repository or folder would deploy a mock and what is missing. This clearly distinguishes it from sibling tools like deploy_mock_from_url, wait_for_github_deploy, or publish_to_github.

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?

Explicit when-to-use guidance is provided: when the user has a repo and asks whether it can serve mocks, or before adding the action to a repo. It does not name exclusions or alternatives, but the context is clear enough for selection.

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 bears the burden. It describes the destructive nature (wiping all mocks and stopping server), provides an equivalent command (`rm -rf ~/.cache/mockzilla-mcp/mocks` plus `stop_locally`), and explicitly states what it does NOT affect ('Does not touch the mockzilla CLI binary or other bridge state'), offering full transparency.

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, well-structured paragraph. It front-loads the primary action, includes a functional equivalent, and adds clarifying statements. Every sentence serves a purpose, with 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?

Given no output schema and no annotations, the description provides complete context: what the tool does, how it relates to siblings (`mock_endpoint`, `stop_locally`), its effects, and its limitations. Nothing essential is missing for correct invocation.

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 schema coverage is 100%. The description adds meaning by explaining the effect, but since no parameters exist, it cannot add parameter-level detail. Baseline 4 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 action: 'Wipe ALL mocks created via `mock_endpoint` and stop the managed server.' It uses a specific verb ('Wipe') and resource ('ALL mocks'), and distinguishes itself from sibling tools like `mock_endpoint` (which creates) and `stop_locally` (only stops server).

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 when the user wants to start fresh,' providing a clear usage context. It does not explicitly state when not to use, but the context is sufficient to infer that this is for complete cleanup; alternatives like `stop_locally` exist for partial actions.

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

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

Annotations only include readOnlyHint:false, so the description carries the behavioral burden. It adds significant context: the mock persists, gets a stable URL, and the returned sim is in 'deploying' state requiring a follow-up call. It does not disclose error handling, authentication requirements, or potential naming conflicts, but the added state transition detail is valuable.

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 sentences, each earning its place: purpose, usage guidance, parameter hints, and follow-up. Front-loaded with the core action and scoping, 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?

Given 0% schema coverage, no output schema, and minimal annotations, the description covers the essential workflow (deploy, then wait). It explains the async nature and the need for a follow-up. However, it doesn't explain all required parameters, which would be necessary for fully autonomous correct invocation.

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 compensate. It clarifies `catalog_spec_id` (from list_catalog_products) and `mount_path` (defaults to spec slug) but leaves `name`, `slug`, `domain`, and `version_id` unexplained. Since `name` and `slug` are required, this is a meaningful gap, though not total.

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 specific verb 'Create' and resource: a HOSTED, SHAREABLE mock from a catalog spec on mockzilla.org. It distinguishes from siblings by specifying catalog-based deployment and contrasting with serve_locally, and the mention of catalog_spec_id differentiates it from deploy_mock_from_spec and deploy_mock_from_url.

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 provides when to use ('durable, team-visible, or reachable from outside their machine') and when NOT to use ('NOT for ephemeral local exploration') with a named alternative (`serve_locally`). Also gives prerequisite guidance to pass `catalog_spec_id` from `list_catalog_products` and instructs the follow-up with `wait_for_deploy`.

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?

Beyond the readOnlyHint=false annotation, the description discloses that the mock persists in the user's account, receives a stable shareable URL, has a 4MB cap, and starts in the 'deploying' state requiring a follow-up call. It does not disclose side effects like slug collisions or overwrites, but the main behavioral traits are clearly surfaced.

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 dense sentences with no filler. The core action and key constraints are front-loaded, usage guidance follows, and the state/follow-up note closes the loop. Every sentence 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?

For a tool with no output schema and sparse input schema descriptions, the description covers the key workflow: input format, persistence, state, and next step. It is still missing explanations for several parameters and edge-case behavior, but the agent has enough context to invoke the tool correctly and proceed to wait_for_deploy.

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 compensate. It explains the `spec` parameter format (YAML/JSON, 4MB cap), but gives no guidance for the required `name` and `slug` parameters or the optional `domain`, `filename`, and `mount_path`. This leaves most parameters semantically underspecified.

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 names a specific verb ('Create'), a specific resource ('HOSTED, SHAREABLE mock on mockzilla.org'), and the input ('inline OpenAPI 3.0+ spec'). It clearly distinguishes itself from siblings like serve_locally, deploy_mock_from_url, and deploy_mock_from_catalog by emphasizing inline spec content and durable team-visible results.

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 states exactly when to use this tool ('when the user pastes spec content AND wants a durable, team-visible result') and when not to ('NOT for ephemeral local exploration'), explicitly naming serve_locally as the alternative. It also tells the agent the follow-up step with wait_for_deploy, leaving no ambiguity about the workflow.

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

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

Annotations only say readOnlyHint=false, so the description carries the behavioral burden. It discloses that the server fetches the spec (with SSRF protection), parses it, returns the sim in a `deploying` state, and requires a follow-up call. This gives the agent real operational context beyond the annotation.

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 dense sentences, each earning its place: core action, usage condition + alternative, and required follow-up. There is no repetition or filler despite the richness of the context.

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 core invocation path is fully covered: source format, URL requirements, target platform, deploy state, and next action. The only gap is the lack of explanation for optional parameters (`domain`, `mount_path`) and not naming `deploy_mock_from_spec`/`deploy_mock_from_catalog` as related alternatives, but these are secondary to correct invocation.

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%, but the description only clarifies `spec_url` (public https URL). It does not explain `slug`, `domain`, or `mount_path`, and those optional parameters are otherwise undocumented in the schema. The required `name` and `slug` are somewhat self-evident, but an agent has to guess at the behavior of the optional fields.

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?

Names a specific action ('Create', a hosted mock), a target resource (mockzilla.org, durable/team-visible), and a precise input ('OpenAPI 3.0+ spec at a public https URL'). It immediately distinguishes this from local/exploratory use, so an agent can tell it apart from serve_locally without deeper inspection.

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 it (user has a spec URL AND wants a durable, team-visible result) and when not to (ephemeral local exploration), naming the alternative tool serve_locally. It also instructs the agent to follow up with wait_for_deploy, which is essential for completing the workflow.

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 and does so excellently: it declares the operation read-only, scopes it to localhost, describes the output categories, and explains the important behavioral caveat that replayed or cached responses do not appear in the history log. Nothing about the tool's behavior is hidden.

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 yet every sentence earns its place: purpose first, then output details, then usage guidance, then a caveat, then constraints. It front-loads the core function and provides actionable detail without 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?

Given no output schema, the description thoroughly explains what the tool returns, when to use it versus a sibling, and an important behavioral limitation. The parameter schema covers the inputs, and the description covers the behavior and interpretation of results, so an agent has everything needed to invoke the tool correctly.

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 input schema already documents `limit` and `service` adequately. The description does not add extra semantic nuance to the parameters, but it does not need to do so given the schema's coverage; it stays at the baseline of 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 uses a specific verb ('Explain what is going wrong') with a clear resource ('the traffic the local server has served') and then enumerates concrete outputs: breakdown by source, status, content type, latency percentiles, and concrete findings. It also distinguishes itself from the sibling `request_history` by mentioning the preference rule, making the purpose unmistakable.

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 instructs the agent to prefer this tool over `request_history` when diagnosing why a response looks wrong, whether data is real or mocked, or why something is slow. The note about replayed/cached responses never reaching the history log also helps the agent interpret missing results and choose this tool appropriately.

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 reveals that the scan is shallow ('Scans one level only'), that large folders are capped with `truncated: true`, and that the full `spec_file_count` is still returned. It does not explicitly state read-only behavior or error cases, but 'scan and report' strongly implies non-destructive 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?

The description is front-loaded with the core purpose, then adds only high-value details: the returned `suggested_input`, exact user triggers, the one-level depth limitation, and truncation behavior. Every sentence earns its place 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?

For a single-parameter discovery tool with no output schema, the description covers what is scanned, what is returned, how to use the output downstream with `serve_locally`, and edge behavior for large folders. Minor omissions such as error handling or path requirements do not significantly harm an agent's ability to call it correctly.

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 a single `dir` parameter with 0% description coverage, and the tool description does not explain what `dir` should contain beyond the phrase 'Scan a directory'. There is no guidance on path format, whether the directory must exist, or whether absolute/relative paths are accepted, so the agent must infer semantics from the parameter name alone.

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

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

The description states a specific verb ('Scan'), a resource ('a directory'), and a concrete outcome ('report what mockzilla can do with it'). It also clarifies the return value (`suggested_input`) and distinguishes the tool from siblings like `serve_locally` by positioning it as the discovery/precursor step.

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 lists triggering user phrasings ('I have a folder of specs/files, what's in it?' or 'mock this directory'), which tells an agent when to invoke it. It also notes the one-level-only scan behavior, implying that deeper recursion requires further calls, though it does not explicitly name alternative sibling tools or when-not-to-use scenarios.

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?

While the readOnlyHint annotation already marks this as safe, the description goes beyond it by explaining the practical consequence of read-scoped access: it cannot deploy and requires reauthentication. This gives the agent useful behavioral context that the annotation alone does not provide.

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

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

The description is compact: three sentences, each earning its place. The first sentence states the core purpose, the second gives a direct usage instruction, and the third explains the access limitation and required remediation.

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

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

For a parameterless tool with no output schema, the description fully equips the agent: it names what is returned, when to call it, and the consequence of read access. No additional context is necessary for correct invocation.

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

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

The tool takes zero parameters and the schema has full coverage, so there is no parameter ambiguity to resolve. The description appropriately focuses on the return values instead, listing org, role, and access, which is the relevant semantic information here.

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 uses a specific verb, 'Return', and names the exact resource: the org, role, and access scoped to the current MCP credential. This clearly distinguishes it from sibling tools like login, logout, and info by focusing on credential context rather than authentication or generic information.

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 instructs the agent to use this once at the start of a session to know which org it is acting in. It also provides a key exclusion: a read connection cannot deploy, and the user must log in again with write access, helping the agent decide when to call login 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 the full behavioral burden, and it delivers: it discloses the non-serving read-only nature, the exact return shape for specs ({title, version, openapi_version, endpoint_count, paths} with operation IDs), the manifest return for packages, and accepted input forms. It does not cover error behavior or edge cases, which keeps it below 5.

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?

Five short sentences, each earning its place: purpose/scope, spec output shape, package output shape, input format, and usage trigger. The verb+scope is front-loaded and there is zero 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?

With no annotations and no output schema, the description must disclose both safety and return values — and it does, enumerating outputs for both input kinds and framing the tool as read-only. The lone gap is a slight ambiguity: the sentence 'Pass input as a local file or a public https URL' follows the package clause without scoping, leaving it unclear whether packages also accept URLs.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds modest clarification by phrasing accepted input as 'a local file or a public https URL' and qualifying the URL as public, but this mostly reinforces rather than extends the schema. No meaningful new semantics are added.

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

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

States a specific verb and resource ('Summarise an OpenAPI spec or .mockz package') and immediately distinguishes itself from the serving/deploying siblings with 'without serving it'. Among tools like serve_locally, deploy_mock_from_spec, and deploy_mock_from_url, an agent can tell this apart without opening any schema.

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

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

Explicitly states the trigger condition: 'Use this when the user wants to know what's in a spec or package before deciding whether to serve or deploy it.' The qualifier 'without serving it' also implies the exclusion of serving/deploying tools. It falls just short of the top bar because no specific sibling tool is named as the alternative.

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 installation methods, cache location, system PATH impact, and uninstall procedure. It is transparent about where files land and how to clean up, though could mention potential network usage or error scenarios.

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 (4 sentences) and front-loads the purpose and a key instruction. It could be improved with bullet points for the methods, but remains clear and avoids 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 simplicity (1 parameter, no output schema), the description is complete: it explains each method, side effects (cache location, not on PATH), and how to uninstall. No critical gaps remain.

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 description adds substantial meaning beyond the schema: it explains each enum value (download: prebuilt binary, go-install: compile from source, go-run: use go run without install), including size, speed, and dependencies. This is essential given 0% schema description 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 'Install the mockzilla CLI for this user' and details three specific methods, distinguishing the tool from siblings like check_cli and serve_locally.

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 instructs the agent to ask the user which method to use and lists prerequisites for each method (e.g., Go needed for go-install/go-run). It does not explicitly exclude scenarios but provides sufficient context for decision-making.

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 largely succeeds: it discloses the return object structure, the 50-defect cap/truncation behavior, and the downstream consequence of unsatisfiable schemas. It does not explicitly state that the operation is non-mutating, but 'Check' and the return contract strongly imply a read-only analysis.

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 dense sentences deliver the purpose, defect examples, return contract, parameter format, usage timing, and version constraint without filler. The purpose is front-loaded and every clause 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?

For a single-parameter lint tool with no output schema, the description is complete: it covers the input type, return fields, result truncation, version restriction, and the situations that warrant calling it. Nothing essential to invoking the tool correctly is missing.

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 describes `input` fully as 'Spec file path or public https URL,' and the description only restates this. It adds no new syntax, resolution, or error-handling details beyond what the schema provides, so the baseline 3 applies.

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

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

States a concrete action ('Check') on a concrete resource ('an OpenAPI spec') with a precise goal: find schemas no value can satisfy. Concrete examples like 'array with a scalar enum' and the 'OpenAPI 3.x only' constraint make the tool's role unambiguous among siblings.

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 tells the agent when to invoke it: before serving/deploying a spec or when a mock returns unexpected validation errors. It does not name alternatives or state exclusions, but the timing guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, and the description adds important non-obvious behavior: it returns recommended runtime settings to compare against the org's tier, and the returned ids/slugs are ONLY usable with `deploy_mock_from_catalog` — not URLs and not valid for `serve_locally`. This materially helps the agent avoid misusing results.

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 main purpose, then adds return behavior, search guidance, and critical usage constraints, then closes with the local alternative. Every sentence adds necessary routing or behavioral information; there is no filler or repetition of the schema.

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 readOnly annotation, no output schema, and three optional parameters, the description covers everything an agent needs: purpose, result semantics, parameter hints, cross-tool constraints, and a local-workflow alternative. It is complete for safe and correct invocation.

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%, but the description compensates by explaining `search` precisely: substring-match by slug or name. `page` and `limit` are left to their conventional pagination meanings and schema constraints, which are reasonably self-evident. The key domain-specific parameter, `search`, is fully clarified.

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

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

The description states a specific verb and resource: 'List the catalog specs... available to attach to a HOSTED sim on mockzilla.org.' It also distinguishes this tool from siblings like serve_locally and deploy_mock_from_catalog by explaining what the returned IDs are and are not for. This leaves no ambiguity about 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 gives explicit usage conditions: use `search` for substring matching, use this tool for hosted deploys, and skip it in favor of `serve_locally` when the user wants a local catalog product. It even names the alternative tool and the exact input format for that fallback, making the decision path explicit.

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 adds useful context: it explains the meaning of the `publishes_mocks: true` flag and the consequence for publishing (updates existing mock vs creating another). It does not detail return format or auth requirements, but for a simple read-only list operation the disclosed behavior 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?

Four short sentences, each earning its place: purpose, action rule, flag meaning, and environment context. The key instruction is front-loaded, and there is no redundant wording.

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 2-optional-parameter list tool with no output schema, the description covers the purpose, user interaction requirement, key flag semantics, and when it is most useful. Minor gaps like pagination behavior or auth prerequisites are not critical enough to lower further.

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 description does not explain either parameter. `owner` has a schema description, but `limit` is only constrained by default/min/max with no stated meaning (e.g., number of repos to return). At 50% schema description coverage, the description should compensate for the undocumented parameter, and it does not.

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

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

States a specific verb and resource ('List the user's GitHub repositories') and immediately clarifies the purpose: to ask the user which repo to publish mocks to. It distinguishes itself from publish-related siblings by emphasizing it is only a listing and decision-support step, not an action that publishes.

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 clear context on when to use the tool ('clients with no shell, where you cannot run `gh repo list`') and gives an explicit behavioral rule ('Never pick one yourself'). It does not name an alternative sibling tool or state explicit when-not-to-use conditions, so it stops short of a 5.

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 details the return structure, notes the condition for ui_url (only when a managed server is running), and explains the body:null behavior. This goes beyond a simple 'lists endpoints' statement, though it doesn't mention any potential errors or 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 three sentences with no wasted words. The first sentence states the core purpose, the second provides essential return details, and the third adds a practical usage pointer. It is front-loaded and every sentence 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?

For a read-only listing tool with no parameters and no output schema, the description fully covers what an agent needs: the exact return format, conditional UI behavior, and a situational usage hint. Nothing is missing that would prevent correct invocation or interpretation of results.

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 and the schema is empty (coverage 100%). There is nothing to describe beyond the schema, so the baseline of 4 for parameterless tools applies. The description doesn't need to add parameter details.

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

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

The description states the exact verb and resource: 'List all endpoints currently mocked via mock_endpoint.' It clearly distinguishes the tool from siblings like clear_mock_endpoints and mock_endpoint by focusing on listing existing mocks. The scope is precise 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?

It provides a clear context for when to use the tool (to see mocked endpoints) and adds a specific usage suggestion: 'Suggest the UI to the user when they want to explore beyond what the agent can show in chat.' However, it doesn't explicitly compare against alternative tools or state when not to use it, though the purpose makes the primary use obvious.

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 supplied, the description carries the behavioral disclosure burden. It states 'Read-only' and explains what the call reveals (pinned recordings, what a matching request returns). It does not cover auth, rate limits, or failure modes, but this is reasonable for a read-only list 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 sentences with no filler; the primary purpose comes first, followed by concrete use cases and a read-only note. Every sentence adds value and the structure is easy to scan.

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 and annotations, the description adequately explains what the tool does, when to use it, and what results conceptually represent. Minor gaps exist around output format or errors, but the agent has enough context to invoke and interpret the tool correctly.

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 50% because 'service' has no description in the schema. The description adds context that the service owns the recordings and that a key provides full detail, but it does little to define the service parameter's format or required semantics beyond that. The key parameter is already documented in 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 uses a specific verb and resource ('List the replay recordings a service currently holds') and clarifies the tool's role in exposing pinned recordings and replay behavior. It distinguishes itself from siblings like request_history and setup_replay by focusing on recording inventory rather than history or setup.

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 gives explicit trigger scenarios: use after setup_replay to confirm capture, or when suspicious that a response is replayed. This is clear contextual guidance, though it does not explicitly name alternatives or exclusions for when not to use the 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 readOnlyHint annotation already covers the safety profile whether this is a safe read operation. The description adds meaningful behavioral context by describing pagination, output contents, and the filtering modes, without contradicting the annotation.

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 tight sentences: the first states purpose and output shape, the second gives the two filtering modes. No repetition, no 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 simple read-only list operation with readOnlyHint and no output schema, the description conveys scope, return contents, and filtering semantics. It is not fully complete because pagination parameters are not spelled out in prose, though they are visible in the 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 compensate. It clearly defines 'sim' and 'search', but leaves 'page' and 'limit' to be inferred from the phrase 'Returns a page.' That is helpful but not fully compensating for the absence of 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 uses a specific verb and resource ('List the sims (deployed mocks)') and scopes them to the current org. It also clarifies the returned fields (refs, statuses, live URLs), making it semantically distinct from sibling tools like list_mock_endpoints even without naming them.

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 provides clear operational context: 'accessible to the current org' and 'Returns a page of sim entries.' It also gives explicit parameter usage rules for 'search' and 'sim', but it does not contrast this tool with alternatives or state 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 full behavioral burden and does so well: it discloses browser opening, the short-lived 127.0.0.1 listener, the config file location, and that it returns immediately with a URL. This gives the agent a realistic model of the 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 compact yet information-dense, starting with the main purpose and ending with side effects. Every sentence contributes: purpose, flow, return behavior, when to use, and side effects.

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 zero-parameter login tool with no output schema, this is complete: the agent knows what triggers login, what happens in the browser, what is returned, where credentials are stored, and how to retry the originating tool. No critical operational detail is missing.

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 and the schema is empty, so the baseline is 4. The description adds useful context by explaining the browser interaction and access-choice flow, which is more than the schema alone could convey.

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

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

States a specific action ('Log in to Mockzilla cloud') and the concrete effect: hosted tools become available. It also distinguishes itself from local tools and from logout by naming the hosted-tool context.

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 when to call it ('when a hosted tool says it needs a login') and what to do next ('call that tool again once the user approves'). It also says local tools never need it, giving a clear exclusion.

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 revokes the connection, deletes saved login, and causes hosted tools to disappear until next login. This is meaningful behavioral context beyond a simple 'log out' statement. It doesn't mention side effects like whether other machines are affected, but for a logout tool this is reasonably 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?

Three sentences, each earning its place: the action, the behavioral effects, and the usage trigger. Front-loaded with the verb and resource. No 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?

For a zero-parameter logout tool with no output schema, the description covers the action, effects, and when to use it. It could mention whether the user will be prompted for confirmation or whether it affects other sessions, but those are minor gaps. The description is complete enough for an agent to invoke it correctly.

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 schema is trivially complete. The description adds context about what the operation does, which is more than needed. Baseline 4 for zero params 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 verb 'Log out' and the resource 'Mockzilla cloud on this machine', and distinguishes it from the sibling 'login' by describing the effect (revokes connection, deletes saved login). It also mentions hosted tools disappearing until next login, which adds clarity about the scope of the operation.

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 call it: 'when the user asks to log out or to switch organization or access level.' This provides clear usage context and implicitly distinguishes it from login and other tools. It doesn't name alternatives explicitly, but the condition is specific enough.

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, and it does so thoroughly. It discloses the write location ~/.cache/mockzilla-mcp/mocks/, server (re)start behavior, endpoint accumulation across calls, literal storage of placeholders, version requirements, and side effects of repeated calls. This is exemplary behavioral disclosure.

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 long but tightly organized: primary use case first, then path rules with examples, then status/header behaviors, then accumulation and conflict rules. Each sentence earns its place by adding operational detail rather than padding.

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 no output schema and no annotations, the description covers selection, invocation semantics, side effects, version caveats, and interactions with related tools. An agent has everything needed to call it correctly and predict the result.

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?

Even with 83% schema coverage, the description adds substantial value: path must be passed exactly as-is with explicit examples, response body conversion depends on type, status/headers enable failure and redirect responses, and omitting response is required for 204/304. These details go well beyond the schema property 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 opening line states exactly what the tool does: 'Quickly mock a single HTTP endpoint without writing an OpenAPI spec.' This clearly distinguishes it from sibling tools like deploy_mock_from_spec and serve_locally. The examples reinforce the precise scope with concrete call patterns.

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 when-to-use guidance: quick single endpoint mocking without a spec. It also names an alternative for a different need—'use serve_locally with errors' for partial failures—and states the mutual exclusivity with serve_locally. This is strong routing that an agent can act on immediately.

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 reveals truncation behavior with `remaining`, explains how inter-topic links render as `(topic id)`, and clarifies that each topic includes a public `url` that should be given to the user but not fetched. This is detailed and 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?

Four sentences, all substantive and front-loaded with the core purpose. Every clause adds operational detail—truncation, link handling, and URL usage—without repetition 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 two-parameter read tool with no output schema and no annotations, the description is exceptionally complete. It covers input selection, response truncation and pagination, link representation, and user-facing URL behavior. An agent has what it needs to call the tool correctly.

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 documents both parameters, so the baseline is 3. The description adds meaningful semantics: `category` reads a whole category in one call, `topics` accepts one or more ids, and large responses may require follow-up reads via `remaining`. This goes beyond the schema's basic type hints.

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 ('Return'), the object ('full markdown'), and the scope ('Mockzilla doc topics'). It is distinct from siblings like mockzilla_docs_topics and mockzilla_docs_search, making it easy for an agent to know this tool reads full doc 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?

The description gives concrete direction on when to use `topics` vs `category`, and explicitly tells the agent not to fetch the `url` because the markdown is the same page. It references mockzilla_docs_topics for id sourcing, though it does not explicitly contrast this tool with mockzilla_docs_search.

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 burden of behavioral disclosure. It clearly states this is a search operation that returns best-matching sections and gives the exact fields returned. It also notes the docs describe the current product, which is useful context. It doesn't mention edge cases like empty results, but for a read-only docs search this is adequate.

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, each earning its place: what the tool does, what it returns, and when to use it. The key information is front-loaded in the first sentence.

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 low-complexity tool with two parameters and no output schema, the description covers purpose, return shape, and usage context. It could be slightly stronger by explicitly pointing to mockzilla_docs_read for fetching full sections, but the phrase 'so you know which topics to read' implies the next step.

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 documents the query parameter with an example. The description reinforces that search is by keyword but adds no new meaning. The limit parameter is not mentioned in the description, though its name, default, and bounds in the schema make its role reasonably inferable.

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

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

The description states a specific verb and resource ('Search the Mockzilla docs by keyword') and defines the return shape ({topic, title, heading, snippet}). It also differentiates itself from mockzilla_docs_topics by explicitly naming when that sibling should be preferred, so an agent can distinguish the 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?

It gives an explicit when-to-use rule: use this when no topic title from mockzilla_docs_topics clearly fits. It also gives a behavioral directive to answer from docs rather than memory, which clarifies the tool's role in the workflow.

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 behavioral disclosure. It states that the docs are files inside the bridge, requiring no network or login, and describes the output format. This covers the key behavioral traits—read-only, offline, and deterministic. Some minor aspects like potential size limits or pagination are not mentioned, but for a simple listing tool this is adequate.

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, front-loaded with the core purpose, followed by output details and a usage tip. Every sentence earns its place: purpose, content breakdown, key behaviors, and when to call it. No redundancy or 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?

For a zero-parameter, no-output-schema tool, the description is fully complete. It specifies what the tool returns (categories with id, title, summary), the content scope, the operational context (no network/login), and even gives usage guidance. An agent has everything needed to invoke and interpret the result correctly.

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, and the schema coverage is 100%, so the description adds no parameter-specific meaning. According to the rubric, a 0-parameter tool gets a baseline of 4. The description's mention of output categories doesn't compensate for missing params (none exist), so it remains at 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 specific verb 'List' and resource 'Mockzilla docs', and distinguishes itself from siblings like mockzilla_docs_read and mockzilla_docs_search by describing its unique output (categories with topics' id, title, summary). It also specifies the scope (product docs and engine docs), making its purpose unmistakable.

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 instructs 'Call it before answering a question about Mockzilla, then read the topics that fit,' which provides a clear when-to-use directive. It implies a follow-up step (reading topics) without explicitly naming the read tool, but the context is unambiguous. It doesn't state exclusions (when not to use), but the positive guidance is strong.

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 behavioral burden. It does well: it reveals the manifest contents, the default output location, and the auto-embedding of git metadata with a suppression flag. It doesn't discuss overwrite behavior or what is returned, leaving minor gaps, but the core side effects and defaults are 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?

The description is compact and front-loaded: first the action/result, then when to use it, then defaults and edge behavior. Every sentence adds information, with no filler or repetition of structured schema fields.

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 6-parameter tool with no output schema and no annotations, the description covers the key call decisions: required dir, output default, git embedding, and intended usage. It doesn't explicitly state the return value or overwrite policy, but the archive-creation behavior and consumer workflow are sufficiently described.

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 meaning by explaining the conditional git-metadata behavior (embedded only when dir is inside a git tree) and how skip_git suppresses it, which goes slightly beyond the bare schema. Other parameter defaults are also reiterated and reinforced in 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 opening sentence names the action (pack), the input (directory of mockzilla services), and the concrete output (.mockz archive). It unambiguously differentiates this from sibling deploy/search tools by establishing that pack produces a distributable bundle rather than starting or serving anything.

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 reach for this tool: sharing a mock setup, snapshotting for a teammate, or publishing. It also explains how the result can be consumed via serve_locally. It does not list alternatives or when-not-to-use conditions, but the when-to-use context plus the consumer note 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, the description carries the full burden of behavioral disclosure and does so strongly. It states side effects up front: uses the user's gh login, may create a repository, commits and pushes, triggers a public deploy, merges an existing services folder unless replace is true, and never overwrites an existing workflow. It also reveals that the public URL means responses are readable by anyone with the link.

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 action and organized into clear paragraphs for usage, required user decisions, side effects, and constraints. It is long, but the complexity of the tool justifies most of it; a few phrases are slightly redundant with the schema, such as visibility being required with no default.

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 mutating, externally visible action with seven parameters and no output schema, the description is remarkably complete. It covers prerequisites, user confirmation steps, side effects, what the tool refuses to do, spec-size limits, and the follow-up tool to call. It even explains the absence of a returned URL, which is essential when there is no output 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 coverage is 100%, so the schema already handles basic parameter definitions. The description adds worthwhile operational meaning beyond the schema: repo must be user-owned and not invented, candidates can come from list_github_repos, visibility has no default and the resulting URL is public either way, and replace/services_dir merge behavior is clarified.

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 names a specific verb and resource: publishing mocks to the user's own GitHub repository and letting the Mockzilla action deploy them. It also differentiates from sibling tools by labeling this the free path for unauthenticated users, a code-review-friendly option, and by explicitly noting that this tool returns no URL while wait_for_github_deploy 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?

It provides explicit when-to-use and when-not-to-use guidance: prefer deploy_mock_from_* for quick logged-in hosted mocks, use this for repo-based/free hosting, and avoid it for real logic or state, which needs the codegen path. It also chains the workflow by instructing the agent to ask the user first, consult list_github_repos, possibly run simplify, and then call wait_for_github_deploy.

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 behavioral burden, and it does well: it characterizes the tool as read-only ('Reads the server's own history API'), clarifies auth needs ('needs no account'), and scopes it to localhost. It does not go into edge-case behavior such as id-without-service or whether listing mutates state, but the explicit read framing largely covers the safety profile.

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 every sentence serves a purpose: what the tool returns, when to use it, how to get detail, its auth/localhost behavior, and when to pick a sibling. The main result is front-loaded and there is no 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 tool with 7 optional parameters and no output schema, the description does enough: it names the returned fields, explains the id/service detail mode, gives the local/no-account context, and routes to diagnose_requests. It does not specify how filters interact with id or describe pagination beyond 'newest first', but the sibling routing and core usage guidance cover the main agent needs.

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 86%, so the schema already explains most parameters. The description adds context for the id+service pair and explains what the returned history contains, but it does not add meaning beyond the schema's parameter descriptions. 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 names a specific verb and resource ('List the requests the running local server has answered'), states the result ordering, and enumerates the returned fields. It also distinguishes itself from sibling diagnose_requests by explicitly saying that tool is for asking what is WRONG with traffic.

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 gives concrete use cases: show what the user's code sent, confirm a call arrived, and find the request to look at next. It also provides an explicit exclusion by directing agents to diagnose_requests when they want problem analysis rather than a listing.

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 behavioral burden and does so thoroughly. It discloses ephemerality, single-server limitation, mount-prefix behavior, the fact that latency/errors/mount/context only work for single specs, and warns against passing catalog IDs. It even explains the returned fields.

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 long but densely packed with essential usage constraints, examples, and warnings. It front-loads the core purpose and then layers behavioral rules and alternatives. Slightly verbose with the URL examples, but each part earns its place for this complex tool.

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, 6 parameters, no output schema, and many sibling alternatives, the description covers everything an agent needs: return shape, constraints, input types, known-API handling, single-server behavior, and cleanup. Nothing critical is missing.

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 by clarifying that input can be a single path/URL or an array, that latency/errors/mount/context apply only to single-spec inputs, and that well-known API names should be resolved to public OpenAPI URLs before passing.

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 starts one local mockzilla server serving any number of APIs together, with explicit contrast to the deploy_mock_from_* siblings. It names the resource, action, and scope precisely, leaving no ambiguity about 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?

It explicitly says to prefer this over deploy_mock_from_* for 'try locally', 'experiment', or 'play with', and explains those alternatives create persistent hosted bundles. It also instructs pairing with stop_locally(pid) and describes the one-server-at-a-time rule with restart 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 provided, the description carries the full burden, and it delivers. It discloses the write side effect, the write scope ('only writes inside the bridge's own mocks dir'), the fallback behavior for user-served folders, and the requirement to restart because config is read at startup. This is exactly the kind of behavioral context agents need.

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 long but every section earns its place: core concept, mandatory user questions, matching syntax, write location, and restart requirement. It is front-loaded with the essential behavior and structured so an agent can extract the call-critical information quickly.

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 having no output schema, the description tells the agent what the tool returns ('recording_scope spelling out what each endpoint is keyed by'), what side effects occur, and what postconditions apply. For a multi-option setup tool, this is complete enough to call correctly without additional context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining operational semantics: match fields come from path, body, and query; body supports dotted paths; path variables are ignored unless listed; and omitting match keys on method+path alone. This meaningfully exceeds what the schema 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 starts with a specific verb and resource: 'Configure replay for a service' and immediately defines the behavior with a VCR analogy: 'record a real response once, then serve it back for every matching request.' It also states the concrete side effect, writing a `replay:` block into config.yml, which distinguishes it clearly from sibling tools like list_replays.

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 pre-call guidance by telling the agent to ask the user two questions before calling, and explains the practical consequences of each choice. It doesn't name alternative tools or exclusions, but the decision context it provides is strong enough for an agent to know when this tool is appropriate.

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—and it delivers. It discloses that the tool writes to disk and returns the path, that `config` causes a pre-processing pipeline (filter + overlay + prune), and that the result is 'a faithful subset.' It does not mention side effects like overwriting existing files or how the random count is seeded, so it's not a perfect 5, but the main behavioral surface is well covered.

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 core action is front-loaded in the first two sentences, followed by a compact bulleted list for the optional-property parameter modes. Every sentence adds information—there is no filler or restatement of the input schema. The structure makes the trickiest parameter semantics scannable.

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 six parameters and no output schema, this description covers the input source, the transformation behavior, the output destination fallback, the full parameter-mode matrix, and the `config` pipeline. The only minor omissions (overwrite behavior, exact return-value shape) are understandable given the description text and the 100% schema coverage; nothing an agent needs to invoke it correctly is missing.

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 already 100%, so the baseline is 3; the description adds genuine value on top by explaining the semantics of `optional` modes (keep all vs. exactly N vs. random range), the mutual exclusivity of `optional` with `optional_min`/`optional_max`, and the `config` preprocessing pipeline. It loses one point because `output`'s fallback behavior is stated but the random-range semantics could have been slightly clearer about the inclusive/exclusive bounds.

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

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

The description states a specific verb (simplify) and resource (OpenAPI spec), enumerates exactly what transformation is applied (drop/reduce anyOf/oneOf, strip x-* extensions, limit optional properties), and distinguishes its output use case from siblings by naming `serve_locally`. This is clearly differentiated from sibling tools like `lint`, `pack`, and `serve_locally`.

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 a spec is too large or too complex to mock cleanly') and names the downstream sibling (`serve_locally`) that should receive the output. It also includes detailed mode-selection guidance for the optional-property parameters (omit, exact N, or min/max range), which routes the agent to the correct parameter combination and even notes the mutual-exclusion requirement.

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?

Despite no annotations, the description fully discloses behavior: stops server, takes no arguments, returns {stopped: bool, pid?, reason?}. 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?

Two concise sentences, each providing essential information. Action is front-loaded. No extraneous text.

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 zero-parameter tool with no output schema, the description explicitly states return format and server uniqueness, making it complete for agent usage.

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, so baseline is 4. Description adds context that it takes no arguments and only one server exists, which is helpful beyond the empty 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?

Clearly states the tool stops the mockzilla server started by serve_locally, specifying the action and resource. Distinguishes from sibling tools by explicitly mentioning the server it stops.

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?

Implies usage context: use after serve_locally when a local server is running. Notes there is only one server. Does not explicitly state when not to use, but the simplicity of the tool makes it adequate.

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, and it does so thoroughly. It discloses the mechanism (runs workflow with delete: true), the prerequisite (workflow_dispatch trigger), the failure behavior ('the result says so'), the permanence of delete_repo, the required scope, and the need for user confirmation. This is comprehensive behavioral disclosure.

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, front-loads the core purpose, then explains mechanics and cautions. Every sentence adds essential information with no fluff 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 two-parameter tool with no annotations and no output schema, the description covers purpose, operation, prerequisites, side effects, and required permissions. It does not specify what the repo parameter should look like or describe the success/error return format, but the phrase 'the result says so' hints at error messaging. Overall it is near-complete for an agent to act correctly.

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 50% (delete_repo has a schema description, repo does not). The description adds value by explaining delete_repo's scope requirement and permanence, but it does not clarify the expected format for the repo parameter (e.g., 'owner/repo'), leaving that gap. It partially compensates but not fully.

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 action: 'Take down the mocks a repository serves, freeing its simulation slot.' It uses a specific verb ('take down') and identifies the resource (repository), and this is the inverse of the sibling publish_to_github, making it distinguishable.

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 gives clear context for when to use the tool (to unpublish mocks) and explicitly states when it cannot work (if the repo's workflow lacks workflow_dispatch). It also instructs to confirm with the user before using delete_repo: true. However, it does not name alternative sibling tools or explicitly compare with publish_to_github, so it stops short of a 5.

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?

Beyond the readOnlyHint annotation, the description discloses that the call blocks, how long it may block, what the return payload contains, which statuses are terminal, and what happens on timeout. It also tells the agent it can retry with the same sim_id, which is important behavioral 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?

Three sentences with no filler: core blocking behavior first, then return shape, then timeout behavior and retry guidance. Every sentence earns its place and the most decision-relevant information is 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?

Given no output schema and minimal annotations, the description provides the return shape, terminal statuses, timeout behavior, and a retry strategy. An agent has what it needs to invoke the tool correctly and interpret the result.

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 0%, so the description carries the full burden. It explains `timeout_s` with default and max values and its effect on blocking behavior, and it clarifies `sim_id` as the identifier of the sim whose deploy is being waited on, including reuse on retry.

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 ('Block until') and names the exact resource and condition: a sim's deploy reaching `active` or `failed`. This unambiguously distinguishes it from deployment-creation and serving siblings like `deploy_mock_from_spec` and `serve_locally`.

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 makes the operational context clear: call it to wait for a deploy to finish, and call it again on timeout. It does not explicitly state when not to use it or name alternative polling strategies, but the blocking behavior and retry guidance provide solid usage direction.

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 behavioral burden. It discloses that the tool reads the workflow log, waits for completion, and returns the URL; it also explains the timeout symptom ('returns with no conclusion') and tells the agent to call again. It does not cover auth or failure modes, but the core polling/log-reading behavior is well disclosed.

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?

Five short sentences, each earning its place. The primary action is front-loaded, and the description avoids filler while efficiently conveying sequencing, timing, and retry behavior.

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 the main orchestration context: when to call, how long to expect, what it returns, and what to do on timeout. It is slightly incomplete on the required repo argument and precise failure behavior, but given the tool's simplicity and no output schema, it provides enough for an agent to use it correctly.

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%, and the description never mentions repo or timeout_seconds. The retry/timeout prose only indirectly relates to timeout_seconds, and repo is left entirely to inference from the tool name and GitHub context, so the description does not adequately compensate for the lack of schema-level parameter 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?

States a specific operation: wait for the Mockzilla workflow run to finish and return the live mock URL from the run log. The wording clearly identifies the GitHub/Mockzilla deployment context, making it easy to tell apart from sibling deploy and wait tools, though it never explicitly names wait_for_deploy as the competing alternative.

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

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

Gives explicit sequencing guidance: 'Call after publish_to_github, or after the user pushes' and explains the expected timing with 'A first deploy takes a minute or two.' It also provides a retry instruction for timeout cases, but it does not explicitly state when not to use this tool or name alternatives such as wait_for_deploy.

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