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

With no annotations, the description carries the full burden and does so well: it discloses the persistence side effect (appends to ~/.bowire/typed-urls.json), the session-scoped in-memory allowlist mutation, and the return payload (whether the URL was new plus list size). These are exactly the behavioral traits an agent needs beyond the bare schema.

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

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

Two sentences, front-loaded with the primary action and its persistence target, with the parenthetical clarifying the file's origin. Every clause carries information (side effects, session scope, return values) with 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 single-parameter tool with no output schema, the description covers the action, its persistence and in-memory effects, the intended usage moment, and even the return values. 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 100% and the single url parameter is documented as "Server URL to allow," so the baseline is 3. The description adds meaning by specifying the URL is what gets allowlisted for bowire.invoke / bowire.subscribe and is written to the typed-urls file, giving the parameter concrete effect beyond the schema text.

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+resource: recording that a URL is now allowed for bowire.invoke / bowire.subscribe, with the concrete effect of appending to a named file. An agent can distinguish this write operation from the read-only sibling bowire.allowlist.show without opening either 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?

It gives a clear when-to-use context ("Use to surface 'the user just typed this URL into the workbench'") and contrasts it with the alternative of re-reading the file. It does not explicitly name bowire.allowlist.show as the read counterpart or state when-not to use it, so it falls just short of 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 the description carries the full burden, and it does disclose the return content: the allowed URLs and the toggles/seed sources (environments seed, typed-URLs seed, --allow-arbitrary-urls) that produced them. The 'show' framing makes the read-only nature clear; there's little destructive risk to disclose for a no-param diagnostic.

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

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

A single sentence, front-loaded with 'Diagnostic' so the agent immediately knows the tool's role. The parenthetical list of feeding toggles is dense but relevant, not 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?

No output schema exists, so the description must cover return values, and it does name both the URL list and the seed toggles. For a simple no-param diagnostic this is essentially complete, with only the missing sibling contrast and prerequisites as gaps.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description's incidental mention of config toggles is not a parameter, so it neither helps nor hurts.

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 verb ('show') and resource ('URLs the agent is currently allowed to call'), and ties it to the invoke/subscribe flow plus the config toggles that produced the list. It clearly reads as a read-only inspection tool, though it never names the mutating sibling bowire.allowlist.permit to sharpen the distinction.

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?

Labeling it 'Diagnostic' implies the when-to-use context (to inspect current allowlist state), but there is no explicit statement of when to prefer this over siblings like allowlist.permit, nor any prerequisite or exclusion guidance. Usage is implied rather than specified.

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 and does reasonably well: it discloses this is a mutating append to an on-disk file, names the default file path, and states the return value (assertion id + attached step). It omits whether existing assertions are replaced vs. appended, permission needs, and failure modes for a non-existent recording.

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?

Front-loaded with the core action, then targeting, then the assertion shape and ops, then the return value. Four dense sentences with no filler, though the op enumeration slightly duplicates the schema enum list.

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 output schema, the description supplies the return shape (assertion id + step), covers the assertion object format across two storage modes, and documents all six parameters including target resolution. Nothing an agent needs to invoke 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 100%, so baseline is 3, but the description adds value beyond the schema: the mutual exclusivity of recordingId/recordingPath and the file-resolution behavior for recordingId are not in the schema descriptions. It also reinforces the path='status' special case and op-specific expected semantics.

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 (Append), resource (test assertion), and target (a step inside an on-disk recording), which is unambiguous and distinct from every sibling tool. An agent can identify exactly what this does without opening the 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?

Explains target selection clearly: recordingId resolves against ~/.bowire/recordings.json, otherwise the supplied recordingPath is used, and the two are mutually exclusive. It doesn't name an alternative tool or state exclusions, since no sibling overlaps, but the operational context is 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?

No annotations are provided, so the description carries the burden and does so well: it discloses the two-step confirmation flow, the shape of the first response ({ pending, confirmationToken, plan }), and the security property that the credential is written to the local store and never echoed back. It stops short of stating error behavior or auth/permission requirements.

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, front-loaded with the core purpose and followed by the invocation workflow and the safety guarantee. Every sentence adds distinct, load-bearing information with no 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?

Covers the essential behavior, first-call return shape, and safety property for a mutation tool with no annotations and no output schema. Minor gaps remain around the result of the confirmed call and error handling, but an agent has enough 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds real value by explaining the runtime relationship between confirm=true and confirmationToken in the two-step flow, which the individual schema fields do not convey on their own.

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 (Store) plus resource (a credential as a named auth recording) and the downstream purpose (so a mock's auth requirement can resolve it by id). This clearly distinguishes it from siblings like auth-recording.list, auth-recording.remove, and auth-recording.capture-flow.

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?

Explains the use case (persisting a credential for a mock's auth requirement) and describes the default two-step invocation and how to complete it. It does not, however, explicitly contrast with the sibling bowire.auth-recording.capture-flow, which an agent would have to disambiguate by other means.

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 substantial work: it discloses that Bowire EXECUTES the flow as an outbound HTTP call, that confirmation is required by default, that secrets come from {{env.NAME}} rather than being inlined, and that an unsupported host produces an error. It does not address idempotency or what happens to an existing recording under the same id.

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?

Dense but front-loaded: the core action and its scope lead, followed by execution semantics, safety mechanics, and the host prerequisite. Every sentence carries information; the CLI/workbench parity clause is the only mildly expendable part.

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 mutating tool with no annotations and no output schema, the description covers the important ground: side effects, confirmation protocol, secret handling, and failure mode on unsupported hosts. Remaining gaps (overwrite behavior on duplicate id, where the token is persisted) are minor but real.

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, but the description adds semantics the schema does not: confirm/confirmationToken implement a two-step pending-confirmation flow, and flow secrets resolve from env vars. It does not clarify id/name/workspace interaction beyond what the schema already says.

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 + resource: it runs an auth flow (defined parenthetically as a scriptable login → token chain) and stores the captured token as a named recording. The parenthetical definition of 'flow' implicitly separates it from the single-request sibling bowire.auth-recording.capture, but the sibling is never named, so the distinction still takes a small inference.

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 real operating context: it is two-step by default (confirm=true / confirmationToken) and requires a host with flow-capture enabled, otherwise it errors. It never states when to prefer this over bowire.auth-recording.capture or how to obtain the confirmation token, so there is context but no explicit alternative 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 carries the full burden and does disclose security-relevant behavior: recordings are credential-free and 'the credential value is never returned'. It also gives the return shape. It does not mention pagination, ordering, or an explicit read-only framing, so it falls short of a 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?

Two tight sentences with zero filler: the purpose and scope come first, the return shape second, and the credential-safety note closes. Nothing is padded or redundant.

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-optional-param list tool with no output schema and no annotations, the description covers purpose, scope, return shape, and a credential-safety guarantee. Only ordering/pagination and an explicit read-only statement are missing, which is minor for this complexity.

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

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

Schema description coverage is 100% and the single 'workspace' parameter is already documented as 'Empty = the shared, unscoped store'. The description adds no syntax or format detail beyond the schema, 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 specific verb and resource ('List captured auth recordings') plus a distinguishing qualifier ('credential-free', 'that a mock's auth requirement can resolve by id'). An agent can tell this apart from bowire.auth-recording.capture, .capture-flow, and .remove without opening a 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?

The phrase 'that a mock's auth requirement can resolve by id' implies the use case (find a recording id to wire into a mock), but there is no explicit when-to-use/when-not statement or named alternative (e.g. vs bowire.auth-recording.capture). Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious traits: idempotency, that a result is reported indicating whether a file was removed, and that the default path is a two-step confirmation. It stops short of stating permission requirements or whether a removed recording is recoverable.

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 tight sentences with zero filler, front-loading the action before the idempotency and confirmation details. 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?

No output schema and no annotations, so the description must stand alone; it covers the action, idempotency, result signaling and the confirmation flow. It leaves unaddressed the destructive-operation concerns an agent would want — authorization scope and reversibility of the deletion.

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 3 is the baseline, but the description adds a relationship the schema does not: that confirm=true and confirmationToken are alternative ways to satisfy the same pending-confirmation step rather than independent options. That is genuine meaning beyond the per-field 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?

States a specific verb+resource ("Delete a captured auth recording") that is unambiguous against siblings like bowire.auth-recording.list, .capture and .capture-flow. An agent can identify this as the destructive counterpart to the recording-capture tools without opening the 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?

The description explains how to invoke it (two-step by default, bypass via confirm=true or a confirmationToken) but never states when this tool is appropriate versus alternatives, nor any prerequisite such as the recording having been captured first. Usage is implied rather than routed.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the operation is read-only/local, that it does not contact providers, and where the data comes from. It omits edge behavior such as what is returned when no results exist or when results are stale, which keeps it from a 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?

Two sentences, front-loaded with the read/roll-up action, and the second sentence is spent on the return shape that would otherwise be undocumented. 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 zero-param, annotation-free tool with no output schema, the description compensates by inlining the full return structure (cells, statuses, failures, summary) and the data source. Only failure/empty-state behavior is left unspecified.

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, so there is nothing for the description to disambiguate and the baseline of 4 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 specific verb+resource: reads contract-verification results under .bowire/contract-results and rolls them into a consumer x provider matrix. It also anchors the output to a known artifact (workbench Contracts rail, `bowire contract matrix` CLI), so an agent can tell this apart from generic siblings like bowire.report.rollup or bowire.assert.

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 use: data must have been written by `bowire contract verify`, and it clarifies the tool is purely local and never calls a provider itself. It stops short of naming an alternative or stating when-not-to-use (e.g. use verify to produce fresh results first), so it is clear context without explicit exclusions.

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 it discloses the key non-obvious trait: the operation is two-phase, returning { pending, confirmationToken, plan } on the first call. That is exactly the kind of state-machine behavior an agent would otherwise get wrong. It stops short of saying the clear is irreversible or whether a pending plan expires.

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 tightly written sentences, front-loaded with the verb and resource, with the two-step contract second. The '#681' issue reference is mild noise but does not obscure the payload.

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

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

No output schema exists, and the description compensates by enumerating the first-call return shape. For a destructive, unannotated tool the main gaps are permission/auth prerequisites and the consequences of clearing (irreversibility, effect on live sessions), but the critical calling mechanics are present.

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

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

Schema coverage is 100%, so baseline is 3. The description adds workflow-level meaning the per-parameter schema text does not: it explains how confirm and confirmationToken interact across calls and what the first invocation returns, which is more than the isolated field descriptions 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 verb+resource ('Clear a cookie jar') and immediately scopes it to either a whole environment jar or a single domain. An agent can tell what the tool does, though it never names the complementary sibling bowire.cookies.list for the non-destructive read case.

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 real usage context for the confirmation flow ('two-step by default... re-invoke with confirm=true or pass the token back'), which tells the agent how to complete the call. It does not say when to prefer this over cookies.list or when clearing is appropriate, so guidance is implied rather than comparative.

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. It does disclose genuinely useful traits — that cookies are grouped per environment and that values are credentials and therefore masked — but says nothing about read-only guarantees, pagination, or permissions.

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

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

A single dense sentence, front-loaded with the verb and resource, followed by the scoping detail and the field enumeration. The field list is slightly stringy but every element carries information.

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

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

There is no output schema, so enumerating the returned fields (domain, path, name, expiry, Secure/HttpOnly/SameSite) plus the masking caveat meaningfully fills that gap. Minor omissions — no pagination or explicit read-only statement — keep it short of a 5.

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 both env and workspaceId (including the 'omit for jars outside any workspace' default) are already documented in the schema. The description only echoes the per-environment scoping; 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 specific verb and resource ("List the cookie jars"), then enumerates the fields returned per environment. It does not explicitly name the sibling bowire.cookies.clear, but the read verb makes the distinction obvious without opening a 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?

The description says what is listed but never when to use this versus bowire.cookies.clear or the env/workspace listing tools. The "per environment" phrasing hints at scoping but supplies no when-to-use or when-not 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 zero annotations the description carries the full burden, and it does an unusually good job: it documents the attempts array outcome taxonomy (ok/empty/partial/error/timeout), guarantees that an empty services list comes with an explanation, and disambiguates 'partial' as services returned plus a fault. It omits auth requirements, timeouts, and whether discovery has side effects, which keeps it short of a 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?

Front-loaded with verb and resource, then the parameter behavior, then the return/failure semantics. Three dense sentences with little waste, though the attempts/detail explanation is longer than strictly needed given the payoff is high.

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?

There is no output schema, so the description must explain returns — and it covers services, methods, the attempts array, its outcome values, and the optional details array. For a discovery tool with an empty-result case, an agent has everything needed to interpret the response.

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, but the description adds genuine semantics the schema lacks: what happens when protocol is omitted (all registered protocols run) and that grpcDescriptorSet is ignored by non-gRPC plugins. It does restate the protocol enum rather than explain it.

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

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

States a specific verb and resource ("Run discovery against a server URL and return the discovered services and methods"), which lets an agent separate it from siblings like bowire.invoke, bowire.network.get, or bowire.mock.list without opening schemas. The scope (one URL in, services+methods out) is 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 explains the protocol filter's behavior ("without it every registered protocol that handles the URL gets a turn"), which is real usage context for a parameter choice. However, it never says when to reach for discover versus bowire.invoke or bowire.network.get, and gives no prerequisites beyond the allowlist note that lives in the schema. Usage is implied rather than stated.

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 behavioral burden. It usefully discloses the storage location and return fields, but does not state that the operation is read-only, whether authentication or permissions are needed, or any pagination or failure behavior.

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

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

The description is a single front-loaded sentence with no redundant or filler text. Every clause earns its place by naming the resource, storage path, and returned data.

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, no parameters, and no output schema, the description provides the essential resource scope and return fields. It could add a brief note on read-only behavior or authentication needs, but for a simple list tool it is largely complete.

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

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

The tool has zero parameters, so the schema is empty and the baseline is 4. The description correctly does not invent parameter semantics, and its mention of returned fields is separate from parameter meaning.

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

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

The description uses a specific verb ('List'), a precise resource ('Bowire environments'), and names the returned fields (names, server URLs, variables). It is clearly distinct from sibling list/show tools such as bowire.mock.list or bowire.record.list because it scopes to environments.

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

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

The description implies its usage by stating what it lists, but it gives no explicit when-to-use guidance, prerequisites, or alternatives. For a zero-parameter list tool this is minimally adequate, though an agent receives no routing help.

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

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

With no annotations, the description carries the full burden and does well: it discloses the read of harPath, the optional file write to outPath, the inline-vs-file return behavior, and exactly what redaction strips (Authorization, Cookie, X-Api-Key, …). It omits error/overwrite behavior for an existing outPath and any permission requirements, which keeps it below a 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?

Three sentences, front-loaded with purpose before the return shape and the redaction option; each sentence carries information. It is dense with parentheticals and inline JSON, which slightly hurts scanability but not enough to waste space.

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?

There is no output schema, and the description compensates by enumerating the returned summary shape { recordingId, stepCount, authHeaders, redacted, outPath?, recording? }, including when the optional fields appear. For a 4-param, single-required import tool this is complete.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters; the baseline is 3. The description restates the same defaults and header examples rather than adding syntax or format detail beyond the schema (the '"-" or omit' rule is the only genuinely additive nuance).

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?

Specific verb+resource: 'Convert a HAR 1.2 trace into a Bowire recording', with the source format (HAR 1.2) pinned down. It is clearly distinguishable from the record.*, mock.* and auth-recording.* siblings, and it names bowire.mock.start as the natural downstream consumer.

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 concrete usage context: 'Pair with bowire.mock.start { recording: <outPath> } to serve the trace back' tells the agent the follow-up workflow, and it explains when to set redactSecrets. It stops short of stating when not to use it or naming a competing import path, so no exclusions are covered.

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 behavioral burden, and it does not discharge it. It says nothing about whether the invoked method mutates state (destructive vs read-only depends entirely on the remote method), authentication requirements, error behavior, or rate limits — significant gaps for a tool that can trigger arbitrary RPCs.

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 with no waste; the purpose is front-loaded and the format clarifications follow. 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?

The 100%-covered schema compensates for most parameter detail, and no output schema exists so return values need not be explained. But with six parameters, no annotations, and an arbitrary-RPC capability, the description is thin on behavior and error/permission context an agent would want before invoking.

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 documents all six parameters, giving a baseline of 3. The description's notes ("body is a JSON string", "metadata is a flat object of header / gRPC metadata") largely restate the schema's own descriptions rather than adding new semantics.

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 (invoke) plus resource (a unary method) and explicitly ties it to its upstream sibling bowire.discover. An agent can distinguish this from tools like bowire.subscribe or bowire.assert without opening a 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?

"discovered via bowire.discover" establishes the prerequisite that the method must first be discovered, which is genuine usage context. However, there is no when-not guidance and no mention of alternatives or exclusions, so usage is only implied rather than spelled out.

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. It usefully discloses the rule-honoring behavior (.bowire/rules.json), the categories of findings, severities, and the exact return shape, but it never states that the operation is read-only/non-destructive or whether invocation has side effects on the workspace.

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?

Purpose is front-loaded in the first clause, and the subsequent clauses (rule source, finding categories, return shape) all earn their place. It is dense and slightly long but free of waste.

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

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

No output schema exists, but the description compensates by spelling out the return shape ({ findings, summary }), and the parameter set is fully covered by the schema. The main omission is the safety/side-effect profile, which is minor for a lint operation.

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 all three parameters are already documented in the schema and the description adds no syntax or format detail beyond them. Baseline 3 applies when the schema does the heavy lifting.

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 (lint) and resource (API surface) and pins its identity by referencing the exact CLI command and workbench rail using the same rules. An agent can tell it apart from a generic discovery tool like bowire.discover because the linting behavior is named explicitly.

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 design-time framing and the mention of the .bowire/rules.json ruleset imply when this tool is appropriate, but there is no explicit when-to-use vs alternatives guidance and no contrast with siblings such as bowire.discover or bowire.contract.matrix. Usage is inferable rather than stated.

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 disclosure burden. It does disclose the payload contents (handle, port, connect URL), which is useful, but says nothing about permissions, whether output is paginated/limited, or what happens when no mocks are running. For a zero-parameter read-only listing the risk is low, so this is adequate rather than rich.

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

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

Two short sentences, zero filler. The scope qualifier ('currently running', 'spawned via bowire.mock.start') is front-loaded before the return-value detail.

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 output schema, the description usefully enumerates the fields each mock entry carries (handle, port, connect URL), which is exactly the compensation needed. It omits edge cases (empty list, whether stopped mocks linger), so it is nearly but not fully complete for such a simple tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless schema applies. The description correctly does not invent parameter-like filters such as port or handle selectors.

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+resource ('List currently running mock servers') and scopes it to mocks 'spawned via bowire.mock.start', which cleanly separates it from bowire.mock.start, bowire.mock.stop, and the other list tools in the family.

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 reference to bowire.mock.start gives clear situational context: use this to inspect mocks you previously started. It does not, however, state any when-not condition or name an alternative tool for a different inspection need, so guidance is clear but not exhaustive.

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

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

With no annotations, the description carries the full burden and does a solid job: it discloses the handle return, concurrency limits, and the non-obvious two-step confirmation protocol including the exact pending payload shape ({ pending, confirmationToken, plan }). It stops short of stating cleanup expectations, error behavior, or whether the referenced recording/schema files must pre-exist.

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 load-bearing, with the core purpose front-loaded and the operational details (handle, concurrency, two-step flow) following in descending order of importance. No filler or repetition of schema content.

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

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

There is no output schema and no annotations, so the description must anchor the agent's expectations, and it does via the pending-call response shape and the handle/stop relationship. Remaining gaps are minor: no guidance on failure modes or whether the mock server lifecycle outlives the session.

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 each of the 8 parameters is already documented in the schema, and the baseline is 3. The description reinforces confirm/confirmationToken semantics but adds no new meaning, and it does not clarify that recording/schema/grpcSchema/graphqlSchema are mutually exclusive input modes.

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 gives a specific verb ('Spin up'), the resource ('local Bowire mock server'), and the two input modes ('replays a recording (or synthesises responses from a schema)'). It also distinguishes itself from siblings by naming bowire.mock.stop as the consumer of the returned handle, so an agent can separate it from mock.list or record.replay.

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 states the context clearly: start a mock, use the handle with bowire.mock.stop, and multiple mocks may run concurrently on different ports. It does not, however, say when to prefer this over alternatives like bowire.record.replay or when a mock is preferable to a live recording, so the alternative-selection guidance is incomplete.

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 whole burden and does deliver the two most important behavioral facts: the operation is idempotent and it returns false (rather than erroring) for an unknown or already-stopped handle. It does not mention permission requirements or the fate of in-flight requests, but the idempotency contract is the crucial 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?

Two compact sentences, zero filler. The core action is front-loaded and the idempotency caveat follows immediately as the second most decision-relevant fact.

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 lifecycle tool with no output schema, the description supplies the prerequisite, the idempotency guarantee, and the return signal, which is enough to invoke it correctly. Minor gaps remain around error/permission behavior, but nothing essential to a correct call 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 description coverage is 100% and there is only one parameter, whose origin ('Handle returned by bowire.mock.start') is already documented in the schema. The description's mention of 'unknown handle' adds no syntax or format detail beyond that, 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 the specific verb 'Stop' on the specific resource 'a mock server', and names the originating sibling 'bowire.mock.start'. An agent can distinguish this from bowire.mock.start, bowire.record.stop, and swait without any schema 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?

The phrase 'previously started by bowire.mock.start' establishes the prerequisite and the lifecycle context in which this tool applies. It does not, however, state explicit when-not conditions or name alternative teardown tools, so it falls just short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does meaningful work: it implies a non-destructive read ('Show'), discloses secret-handling behavior ('Passwords are shown only as their reference, never the value'), and reveals it exposes per-layer provenance and misconfiguration state. It does not mention auth/permission requirements or rate limits, so it stops short of full coverage.

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

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

A single front-loaded sentence that leads with the core purpose before the parenthetical breakdown of returned fields; almost every clause earns its place. It is dense and slightly list-heavy, but not padded.

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?

There is no output schema or annotation coverage, so the description must describe the return surface, and it does so thoroughly (proxy config, bypass list, CA bundle, provenance, misconfig, plugin eligibility). The only gap is the absence of permission/scope prerequisites for a settings-inspection call.

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% and there is a single optional parameter whose 'omit for global settings' semantics are fully documented in the schema. The description adds nothing about workspaceId scoping, so the baseline of 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 specific verb and resource (show how outbound connections leave the machine) and enumerates exactly what it reports: proxy mode/URL, bypass list, CA bundle, layer provenance, misconfigurations, and plugin proxy eligibility. No sibling tool (env.list, allowlist.show, discover, etc.) covers network egress configuration, so the agent can distinguish it immediately.

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

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

Usage is implied rather than stated: this is clearly a diagnostic/inspection call for outbound proxy setup, and 'what is misconfigured' hints at troubleshooting. However, there is no explicit when-to-use framing, no prerequisite conditions, and no named alternative to prefer.

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

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

With no annotations, the description must carry the full burden, and it does disclose real behavior: the backing file (~/.bowire/recordings.json), the summary-only return (step bodies omitted), and the fields exposed. It does not state permissions or error behavior, but for a zero-parameter read-only enumeration that gap is minor.

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 compact sentences with no filler, front-loading the action and resource before the caveat about omitted step bodies. Every clause carries information the schema does not.

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 output schema, the description correctly compensates by enumerating the returned fields (id, name, step count, captured at). The only soft spot is the shaky '(planned)' reference to record.replay, which muddies the completeness of the routing story.

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 no parameters, so there is no parameter semantics to document; the baseline for a 0-param schema applies. The description instead spends its space on output shape, which is the right allocation.

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 (List) and resource (Bowire recordings), plus the storage location and the exact fields returned. It explicitly separates itself from the sibling record.replay tool, which handles detail retrieval, so an agent can pick between them without opening either 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?

Tells the agent when this tool suffices (summary listing) and where to go for step bodies, which is genuine routing guidance. It loses a point because record.replay is described as '(planned)' even though it appears as a live sibling tool, leaving the fallback path ambiguous.

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

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

With no annotations, the description carries the full burden and does well: it discloses the mode switch, the auto-open fallback when no session exists, the returned session state, and the two-step confirmation gate. It omits auth/permission needs, reversibility, and side effects on existing recordings, so it isn't fully complete.

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?

Front-loaded with the core action, followed by the fallback behavior, return value, and the confirmation gate. Each sentence carries information, though the confirmation-gate sentence is somewhat implementation-heavy.

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 4-param tool with no output schema and no annotations, the description covers the action, fallback, return value, and confirmation flow adequately. It could say more about permissions and side effects, but nothing critical to invoking 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 100%, so each parameter (confirm, recordingId, workspaceId, confirmationToken) is already documented in the schema. The description reinforces the confirm/confirmationToken flow but adds no syntax, format, or constraint detail beyond that 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?

States a specific verb and resource ('Switch the active server-side recording session into replay mode') and scopes it to a recording id. It is clearly distinguishable from siblings like bowire.record.start, bowire.record.stop, and bowire.record.list because it is about entering replay mode, not starting/stopping/list.

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 clear operating context: it covers the case where a session is already open vs. when none is open, and explains the default two-step flow versus the confirm=true shortcut. It doesn't name alternative tools or explicit exclusions, so it stops short of the top mark.

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 does so well: it discloses the two-phase pending/confirmation handshake, that capture-mode invokes buffer until stop, the return shape of the first call, and the 409-equivalent failure when a session is already open. It omits auth requirements, rate limits, and what happens to an abandoned session, which keeps it from a 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?

Front-loaded with the core action, then layers lifecycle, protocol, and failure mode in a logical order with no filler sentences. The issue-reference parenthetical ("#285") is noise an agent doesn't need, and the sentence is dense, but nothing else is wasted.

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

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

With no output schema, the description compensates by naming the first call's return fields ({ pending, confirmationToken, plan }) and the failure behavior, and it covers the mode and lifecycle context an agent needs. For a six-parameter session-control tool, nothing essential 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 description coverage is 100%, so the baseline is 3, but the description adds genuine meaning by explaining what each mode actually does (record live invokes vs. proxied flows vs. drive replay) rather than just listing enum-like values. It stays silent on name/workspaceId/recordingId semantics beyond what the schema already states.

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?

Opens with a specific verb+resource ("Begin a new server-side recording") and immediately bounds the operation by naming bowire.record.stop as the terminating counterpart. An agent can distinguish this from siblings like record.replay and record.list without opening the 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?

Explains the three modes (capture/proxy/replay) and the two-step confirmation flow with an explicit re-invoke condition, plus the one-active-session-per-process precondition. It does not explicitly route the agent between this tool and the sibling bowire.record.replay, so it falls just short of full when-vs-alternative guidance.

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

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

With no annotations, the description carries the full burden and does so: it discloses the persistence target (~/.bowire/recordings.json), the return payload { stopped, recordingId, stepCount }, idempotent behavior with the exact non-active response shape, and the confirmation gate. That is unusually complete behavioral disclosure for a mutation tool.

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

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

Four dense sentences with no filler; the core action and its side effect are front-loaded, followed by return shape, idempotency, and the confirmation nuance in descending order of importance.

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?

There is no output schema, so the description correctly enumerates the return fields itself, and the idempotent edge case is spelled out with an exact response. Nothing an agent needs to call this 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema by explaining that confirm=true skips the confirmation gate and that the default is a two-step flow. The confirmationToken parameter is left to the schema, which is acceptable given full 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?

States a specific verb ('Stop') and resource ('the active server-side recording'), plus the concrete side effect of flushing the buffer to ~/.bowire/recordings.json. It is trivially distinguishable from the sibling bowire.record.start without opening either 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?

Explains the operating conditions clearly: it only acts on an active session, returns a no-active-session result otherwise, and defaults to a two-step flow unless confirm=true. It never explicitly points to the alternative (bowire.record.start) for beginning a session, so it stops short of full when/when-not routing.

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 and does well: it declares the tool is 'purely local', reads only files that already exist, never calls a service, and walks directories recursively. It also spells out the return shape since no output schema exists. It stops short of 5 only because it doesn't say what happens when nothing is found beyond the 'skipped' counter.

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 purpose and locality constraint are front-loaded, and each sentence carries information (sources, locality, return shape). The trailing return-value sentence is long but earns its place because there is no output schema to carry it.

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

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

No annotations and no output schema, so the description must cover both the behavioral profile and the return contract — and it does, listing the sources read, the locality guarantee, and the full response shape with the severity vocabulary. 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 100% and both params are documented, so the baseline is 3. The description adds genuine value beyond the schema by stating that directories are walked recursively and that reports are read from the given paths, which clarifies the semantics of the 'from' parameter.

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 ('Roll the reports ... into one view across services') and frames the scope as 'the portfolio question', which distinguishes it from per-artifact siblings like bowire.lint or bowire.contract.matrix. An agent can identify the aggregate-across-services role without opening the 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?

The description gives clear context for when this tool applies — aggregating existing reports into a portfolio view — and the sources it consumes. It does not name an explicit alternative or a when-not condition (e.g., use bowire.lint for a single fresh lint), so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does disclose the non-obvious behavior: frames are buffered until the sample window elapses and returned as raw strings for the agent to decode. It omits auth requirements, error behavior for non-streaming methods, and whether the call blocks, so it falls short of 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?

Two sentences, both front-loaded and load-bearing: the first defines the operation and scope, the second defines the return format. No filler or repetition.

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

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

For a 7-parameter streaming tool with no annotations and no output schema, the return-shape note is valuable, but routing guidance against bowire.invoke and failure/reconnection behavior are missing, leaving real gaps for an agent to fill by inference.

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 all 7 parameters are already documented in the schema (including durationMs's clamp to MaxSubscribeMs). The description adds no per-parameter meaning beyond that, 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?

The description states a specific verb and resource: 'Subscribe to a streaming method', and enumerates the protocol shapes (server-streaming, SSE, MQTT topic, websocket). This distinguishes it from a unary call like bowire.invoke, though it never names a sibling explicitly.

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 mention of streaming protocols and a sample window implies the use case (consuming streaming endpoints), but there is no explicit when-to-use vs. when-not guidance and no reference to alternatives such as bowire.invoke or bowire.network.get.

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