pipehero

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, and the description reinforces this by explaining the mechanism: same-name examples are replaced, so repeats are safe. It adds a useful behavioral fact but does not cover what happens to other examples on the endpoint or any 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?

Two short sentences, the core action is front-loaded, and the second sentence delivers the replace/idempotency fact that an agent actually needs before calling. 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 9-param tool with full schema coverage and no output schema, the description covers purpose and write semantics adequately; it could say a bit more about how the example is identified on the endpoint (name uniqueness scope) and what is returned, but 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% with per-field examples, so the schema already carries the parameter burden. The description only echoes 'endpoint' and 'name' implicitly and adds no syntax or constraint detail beyond the structured fields, 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 ('Save a response example on an endpoint') and illustrates with a concrete case (a 402 declined-card response). It is clearly distinct from sibling tools like upsert_api_endpoint or save_captured_request, but never names those neighbors to reinforce 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?

The example scenario implies when the tool is useful (documenting non-2xx responses), but there is no explicit when-to-use/when-not framing and no mention of the endpoint_id vs method+path alternatives, which are real routing decisions an agent must make.

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, destructiveHint=false, and closed-world scope, so safety is covered. The description adds non-annotated context worth having: a Pro/Team plan requirement, the presence of request_id in every finding, and the shape of what is returned. No mention of cost, rate limits, or behavior on sparse traffic.

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 comparison itself, then the finding taxonomy, then the remediation path. The taxonomy list is long but earns its space given there is no output schema; nothing is 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 output schema, the description usefully compensates by enumerating return contents and the request_id field. All three params are documented in the schema and plan gating is disclosed. Minor gap: no guidance on how many findings to expect or what an empty result means.

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%, including the limit default of 200 and max of 500, so the schema carries the parameter burden. The description only implicitly gestures at collection and tunnel ('a collection's docs', 'traffic a tunnel captured') and adds no format or syntax detail beyond the schema.

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

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

Specific verb and resource: compares a collection's docs against captured tunnel traffic, and the enumeration of finding types (undocumented routes, unexampled status codes, type mismatches, undocumented query params, dead documented fields) pins down the output precisely. Clearly distinct from sibling mutation tools like upsert_api_endpoint and save_captured_request, which it names as downstream actions.

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

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

States an explicit trigger ('Use it to find out what drifted after a code change') and routes the agent to concrete next steps: pass request_id to save_captured_request, or fix docs with upsert_api_endpoint / add_api_example. Missing only explicit when-not-to-use conditions or prerequisites beyond the Pro/Team qualifier.

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 create semantics (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the safety profile is covered. The description adds one useful behavioral fact – the collection is created empty – but says nothing about name collisions, whether duplicates are rejected, or what happens to an existing collection of the same name.

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, zero filler; the core action comes first and the routing guidance follows. Every clause 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?

For a simple two-parameter create with annotations covering mutability and no output schema to explain, this is nearly complete. The one meaningful gap is uniqueness/repeat-call behavior, which matters given idempotentHint=false.

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 both parameters (name, description) are documented with examples in the schema, so the description adds no parameter-level detail. 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 names a specific verb and resource ('Create an empty API collection') and explicitly differentiates itself from the two siblings that also populate collections. An agent can pick it out of the 24-tool list 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?

It gives concrete routing rules: use import_api_spec when an OpenAPI file exists, use upsert_api_endpoint to fill from code. That names the alternatives and the condition that selects each, which is exactly what an agent needs.

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 signal destructive=true, but the description adds valuable context: deleting also removes examples and that the action 'Cannot be undone.' This goes beyond the structured hints, explaining the blast radius and irreversibility.

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 short sentences with no filler. The primary action, the triggering condition, and the key warning are all front-loaded and relevant.

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, combined with the detailed schema and annotations, fully covers what the tool does, when to use it, and the important consequence of irreversibility. No output schema exists, so return values need not be explained.

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 parameters are already well documented. The tool description does not add new parameter-level semantics, but none are needed because the schema descriptions already explain path, method, endpoint_id, and collection_id clearly.

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: 'Delete an endpoint and its examples.' It clearly differentiates from siblings like get_api_endpoint, run_api_endpoint, and upsert_api_endpoint by indicating the destructive action.

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 gives the condition to use this tool: 'Use when the route no longer exists in the code.' It does not explicitly name alternatives or when not to use it, but the context is clear and sufficient compared to sibling tools.

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 destructiveHint=false, so the safety profile is covered externally. The description adds only the format/serialization context; it says nothing about output size, pagination, or whether all endpoints are guaranteed included, which would matter for large collections.

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, front-loaded with the action and formats. Nothing is redundant or buried, though the second sentence is more sales pitch than spec.

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?

A simple read-only, two-parameter tool with full schema coverage and no output schema; the essentials are present. Only minor gaps remain around output characteristics (size/limits) for very large collections.

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 format parameter already documents the enum, its default, and the spec versions. The description merely repeats that OpenAPI 3.1 or Postman 2.1 is chosen, adding no syntax or behavior beyond the schema.

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

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

States a specific verb (export) and resource (an API collection) plus the two output document formats, so an agent can distinguish it from get_api_collection or list_api_collections. It stops short of explicitly contrasting with those siblings, but the scope 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?

"Handy to read the whole API at once" gives an implied use case (want a full picture rather than browsing endpoints), but it never says when to prefer this over get_api_collection or when not to use it, and names no 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?

Annotations already declare the operation as read-only, non-destructive, and closed-world, so the safety profile is covered. The description adds useful context about what is returned: folders, endpoint fields (id, method, path, name, version, example count), and environments with variables. It does not describe error behavior or response shape beyond contents, but the return detail is substantial.

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 efficient sentence with no wasted words. The core action and returned content are front-loaded, and the parenthetical detail clarifies endpoint fields without becoming verbose.

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

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

There is no output schema, so the description must carry return-value information, which it does by listing folders, endpoint attributes, and environments with variables. It is nearly complete for a read-only retrieval tool, though it could note behavior when the collection is not found or when the id is invalid.

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 single collection_id parameter is already well documented in the schema ('Id from list_api_collections'). The description does not add parameter-specific meaning beyond what the schema provides, making the baseline score 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 ('Get one collection') and enumerates the returned data (folders, endpoints, environments). It is clear but does not explicitly distinguish itself from sibling tools such as list_api_collections or get_api_endpoint.

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?

There is no explicit guidance about when to use this tool versus alternatives like list_api_collections or get_api_endpoint. The usage is implied by the retrieval-by-id nature and the schema's note that collection_id comes from list_api_collections, but the description itself provides no routing instructions.

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 destructiveHint=false, so the agent knows this is a safe read operation. The description adds the scope of what is retrieved (full endpoint details) but does not disclose additional behavioral aspects such as permissions, rate limits, or side effects. Since annotations cover the safety profile, a 3 is appropriate—some value added but not rich context.

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

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

The description is a single, tightly packed sentence that front-loads the core purpose ('Get one endpoint in full') and immediately enumerates the return contents. There is zero fluff, and every clause adds value. It is exceptionally concise and well-structured.

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

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

For a read-only getter with 4 params (1 required) and no output schema, the description provides enough context: it explains what is returned and how to identify the endpoint. The schema covers parameter details. It does not mention potential error conditions or prerequisites, but given the annotations and schema, these are not critical. It could be slightly more complete by noting that collection_id is required, but that is already 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?

The schema has 100% coverage, so all parameters are documented. The description adds the crucial semantic that endpoint_id and method+path are alternative identification methods, clarifying their mutual exclusivity and the expected usage pattern. This goes beyond the schema's individual parameter descriptions, which don't mention the relationship between them.

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 a specific verb ('Get') and resource ('one endpoint'), and specifies exactly what is returned (description, parameters, headers, request body, saved response examples, version). It also distinguishes itself from siblings like get_api_collection (which gets a collection) and list_api_collections (which lists) by focusing on a single endpoint. The identification methods are clearly outlined, leaving no ambiguity about the tool's function.

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 identify the endpoint (by endpoint_id or by method + path) but does not explicitly contrast with alternatives like get_api_collection or list_api_collections. The context is clear: use this when you need full details of a single endpoint. However, it lacks explicit exclusions or when-not-to-use guidance, so it's not a perfect 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?

Annotations already declare readOnlyHint/no-destructive, and the description does not contradict them. It adds substantive behavior beyond annotations: the page is read-only, secrets are hidden, the link is immutable ('never changes'), and `shared: false` indicates absence of a link. That is meaningful context for a read call whose return content matters.

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 tightly-packed sentences, front-loaded with the core action and scoping semantics. The parenthetical is information-dense rather than wasteful, though the description is on the busier side.

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 carries the return-value burden and does so: it lists what the link shows and who can open/was invited, plus the stable-link guarantee. Nothing an agent needs to call or interpret this tool 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 all four parameters (path, method, endpoint_id, collection_id) are already documented in the schema, including the method+path vs endpoint_id alternative. The description adds no per-parameter detail, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource ('Get the shareable link of an endpoint') and immediately clarifies what that link is (read-only page with docs, examples, latest run). It names the sibling 'share_api_endpoint' as the counterpart, so an agent can distinguish it from related sharing tools 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?

Explains the use case ('put the link in a PR, an issue or a message') and clarifies the `shared: false` state with a pointer to share_api_endpoint. It gives clear positive context but no explicit when-not-to-use 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine value by disclosing what comes back — both the request and the response, including headers and body — which is not derivable from the annotations and helps the agent anticipate payload size and shape.

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 with no filler. The key scoping facts — one request, full request and response, by id — are all in the opening clause.

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

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

For a simple two-parameter read tool with full schema coverage and clear annotations, the description covers purpose and return content adequately. It does not mention behavior when the id is unknown or whether payloads are truncated, which would have made it fully 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%, and the schema itself explains that id comes from list_requests and subdomain from list_tunnels. The description adds only the phrase 'by id', so it neither compensates for nor extends the schema; 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?

Specific verb + resource: retrieves the full request and response (headers + body) of a single captured webhook by id. It implicitly contrasts with list_requests by emphasizing 'one captured webhook' and 'full ... headers + body', so an agent can tell it apart from the listing sibling 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?

The description implies you call this when you need the complete payload of an already-identified request, but it states no explicit when-to-use/when-not or names any alternative (e.g. replay_request or list_requests). The provenance of the id is handled in the schema rather than the description.

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

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

Goes well beyond the annotations by disclosing atomicity semantics ("All or nothing"), the plan-limit precheck, and that credentials are stripped and become variables. What it does not disclose is the result of the call (no output schema exists), e.g. whether the new collection id is returned.

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, front-loaded with what is imported and where it goes, followed by the behavioral guarantees and the YAML caveat. No filler and every clause 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?

Covers formats, destination, atomicity, limits and credential handling for a 4-parameter mutation tool with full schema coverage. The remaining gap is the absence of any statement about what is returned, which matters given 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 description coverage is 100%, so the schema already documents `name`, `format`, `content` and `collection_id` with examples and an enum. The description adds only marginal framing (that `collection_id` means append instead of create) and does not compensate with format-specific content requirements.

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 (import) plus the three accepted source formats and the two destinations (new collection or `collection_id`). An agent can tell it apart from `create_api_collection` by the fact that it ingests a spec document rather than building one, though no sibling 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?

Gives real preconditions: convert YAML to JSON first, plan limits are checked before import, and everything is all-or-nothing. The `collection_id` sentence implicitly frames the create-vs-append choice, but no explicit alternative tool is named for related tasks like exporting.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a little context about collection contents (examples and environments) and the intended use, but does not go deeper into response shape, pagination, or other behavioral traits. With annotations present, this is adequate but not 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?

The description is a single, well-structured sentence: it leads with the action, specifies the resource, adds a clarifying parenthetical, and ends with a practical use-case. Every word earns its place, with zero 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 list tool with no parameters and no output schema, the description gives the essential information: what is being listed and why an agent would call it (to find a collection_id). It doesn't describe the return format, but since the purpose is to locate an ID, the missing detail is minor. With annotations covering risk, this 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 doesn't need to explain parameters; it only optionally notes the workspace scope, which is already implied by 'the workspace's'. No parameter clarification is missing.

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') and clearly identifies the resource ('the workspace's API collections'), with a parenthetical clarifying what collections are (saved endpoints with examples and environments). It also states the intended outcome ('Start here to find a collection_id'), which distinguishes it from siblings like get_api_collection that require an ID.

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 context: 'Start here to find a collection_id.' This tells an agent when to use this tool (as the first step for operations needing a collection ID). However, it does not explicitly state when not to use it or name alternative tools for the same purpose.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by enumerating monitor states and the last-check details it returns, and by clarifying that it is read-only because people decide what to monitor. It does not cover pagination or authorization requirements, so it is not exhaustive.

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 what the tool shows, then gives the operational scenario and read-only clarification. It is two compact sentences with no wasted preamble.

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 one-parameter, read-only listing tool with no output schema, the description supplies the important return-value context (monitor states, last check, failing duration) and the intended use case. Nothing essential for correct invocation appears to be 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 the single parameter is documented as 'Id from list_api_collections.' The description only implies collection scoping and does not add syntax or source details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it shows which endpoints of a collection are checked on a schedule and reports their monitoring state. It also enumerates the returned information (state, last check status, latency, error, failing since), making the tool clearly distinguishable from siblings like list_api_runs or get_api_endpoint.

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 scenario: use it to find out what is broken in staging or production, then read the endpoint and its code. It does not explicitly say when not to use it or name a competing sibling alternative, but the intended context is clear.

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

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

Annotations declare readOnlyHint=true, and the description adds context about the review workflow (pending_review, statuses) without contradicting the annotations. It explains what the statuses mean (pending, approved, rejected with reason, failed with why), adding value beyond the annotation's safety hint.

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

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

The description is two sentences, front-loaded with the direct purpose ('See what happened to the changes you proposed') and then provides necessary context and status details. No wasted words; it efficiently conveys both when to use and what to expect.

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 is sufficient: it explains the review context, the statuses returned, and the purpose. It doesn't mention pagination or sorting, but these are not critical for a simple list tool, and the description covers everything an agent needs to decide to call 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?

The tool has zero parameters, so the description doesn't need to explain any. Per rubric, 0 params baseline is 4. The description adds no parameter info, which 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 lists proposals and their statuses, and frames it as checking what happened to proposed changes. This distinguishes it from sibling list tools (collections, runs, requests) by focusing on the proposal review workflow.

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 context that some workspaces review AI changes and that this tool tells whether a change went through, which implies when to use it. It doesn't explicitly name alternatives or exclusions, but the purpose is clear enough that an agent would know this is the tool for checking proposal status, not for listing collections or requests.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond that: result ordering (newest first), the default page size, and a sketch of the returned content ('who/what was sent and what came back') — important since there is no output 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 short sentences, front-loaded with the resource and its ordering/limit, followed by a use cue. No wasted text, though the second sentence is close to redundant with the first.

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 five parameters and no output schema, the description should say more about what a 'run' record contains and how results are selected (endpoint_id vs method+path). The schema fully covers inputs and the safety profile is in annotations, so it is adequate but not complete.

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

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

Schema coverage is 100%, so every parameter including the method+path vs endpoint_id alternative is already documented. The description only restates the default limit and ordering, adding little semantics beyond the schema — 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?

Names a specific verb+resource ('recent runs of an endpoint') and states scope (newest first, default 5) plus what the runs contain ('who/what was sent and what came back'). It is clearly distinct from sibling request-oriented tools like list_requests or get_request, though it never names an alternative 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?

'Use to see what happened the last time it was run' gives an implied context of use, but there is no guidance on when to prefer this over list_requests, get_request, or replay_request, and no prerequisites (e.g., needing a collection_id first).

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful context beyond that by naming the returned fields (id, method, path, status, bodies), but says nothing about how far back 'recent' reaches, result limits, or ordering.

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 zero filler: the action and scope come first, the return shape second. Nothing is repeated from the title or annotations.

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, read-only listing tool with no output schema, the description covers purpose and the shape of returned records, which is the essential gap. It falls slightly short on result volume and time-window bounds, which an agent would need to interpret 'recent'.

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 subdomain parameter is fully documented there with an example drawn from list_tunnels. The description adds no parameter-level meaning beyond the schema, 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?

The description states a specific verb and resource ('List recent webhooks/requests captured for a tunnel') and names the entity that scopes it. It does not explicitly contrast with the closely related 'get_request' sibling (single-request retrieval), which is the main ambiguity for an agent.

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?

There is no explicit when-to-use guidance, no prerequisites, and no named alternative (e.g., use get_request for a single request's details, list_tunnels to discover subdomains). The only routing hint, 'from list_tunnels', sits in the schema rather than the description.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the scoping to the user's own tunnels and the 'currently online' status, giving modest extra context beyond the structured annotations, though no rate limits or auth details are 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?

The description is a single, tightly written sentence that front-loads the action and resource, earning its place with zero wasted words.

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

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

For a simple, parameterless, read-only list tool, the description adequately conveys what the tool does and what the user gets (tunnels plus online status). The lack of an output schema or pagination details is not a major gap given the tool's simplicity and the annotation coverage.

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

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

The tool has zero parameters, so the baseline is 4 per the rubric. There is no parameter information needed, and the description correctly implies that no inputs are required to list tunnels.

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') and identifies the exact resource ('the user's Pipehero tunnels') plus the output detail ('whether each is currently online'). This clearly distinguishes it from the sibling request/webhook tools.

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

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

The description makes clear it is for listing the user's tunnels and their online status, providing unmistakable context for use. It doesn't explicitly name alternatives or exclusions, but the sibling tools are all request-focused, so the usage context is evident.

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 destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the risk profile is covered. The description adds the operational prerequisite that the local tunnel process must be alive, which is useful, but says nothing about what happens on failure or that a replay re-delivers a real outbound request to the user's machine.

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 with the action first and the operational caveat in parentheses. Nothing is wasted and nothing important is buried.

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, annotation-rich tool with no output schema this covers the essentials, but it leaves the agent without the outcome of the call (what a successful replay returns) or how it differs from the near-identical `send_test_webhook` sibling.

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 each parameter already documents its source (`list_requests`, `list_tunnels`) with a concrete subdomain example. The description adds nothing about the two parameters beyond the schema, so 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 ('Replay') and resource ('a captured webhook') plus the destination ('the user's localhost'), so the action is unambiguous. It does not, however, distinguish itself from the sibling `send_test_webhook`, which an agent could plausibly confuse it with.

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 parenthetical gives one real precondition — the tunnel CLI must be running — which is genuine when-to-use context. Beyond that there are no exclusions or explicit alternatives; the agent must infer the split from `send_test_webhook` on its own.

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 flag destructive/openWorld/non-idempotent, and the description adds substantial detail beyond them: the 20 KB body truncation, tunnel requirement for local, that staging/prod egress from the cloud and only reach public addresses, and the prod-write confirmation gate. This is exactly the side-effect and prerequisite context an agent needs before firing a real request.

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-loads the action and return shape, then layers prerequisites and the prod safety gate in a tight four sentences with no filler. Minor awkwardness in 'Send an endpoint against an environment' keeps it from a 5.

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?

Seven parameters are all schema-documented, there is no output schema but the description describes the return shape (status, headers, truncated body), and the risky path (prod write) is fully gated. Nothing an agent needs to call this safely 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, but the description adds meaning the schema does not: environment names carry different execution paths and reachability, and confirm_write_to_prod should only be set after explicit user agreement. That elevates it above the schema-only 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 ('Send an endpoint against an environment') and immediately defines the outcome ('return the real response (status, headers, body up to 20 KB)'), which separates it from siblings like replay_request or send_test_webhook that also produce traffic. An agent knows this executes a live HTTP call rather than inspecting or editing an endpoint.

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 a clear use case ('check that the code you wrote behaves as documented') plus the routing conditions for local vs staging/prod and the prerequisite that the CLI must be running. It lacks an explicit 'use X instead' pointer to a sibling, so it stops short of the top score, but the when-to-use context is unambiguous.

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

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

Annotations only declare the safety profile (non-readOnly, idempotent, non-destructive, closed-world); the description adds the substantive behavior: route-matching decides whether an example is appended or a new endpoint is created, credentials/cookies/signatures are replaced with {{variables}}, only JSON bodies are retained, and duplicate examples are skipped. These are exactly the side effects an agent needs to predict before mutating a collection.

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 dense sentences, each carrying distinct information: input source, branching behavior, sanitization, dedupe rule, and intended use. Front-loaded with the core action and free of 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 7-parameter mutation tool with no output schema, the description covers outcomes, sanitization, and idempotency well. It does not state what is returned (created endpoint id? example id?) or any permission/auth prerequisites, which would help an agent chain follow-up calls.

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 the matching rule ('If an endpoint already covers the route') that explains how method+path interact versus endpoint_id — context the schema only hints at with 'Alternative to method + path.' It does not explain the folder parameter's default or what happens when path is supplied without method.

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 ('Document a real request captured by a tunnel') and immediately clarifies the source of the input ('get its id from list_requests'). It also spells out the two possible outcomes (example added to existing endpoint vs. endpoint created), which distinguishes it clearly from siblings like add_api_example and upsert_api_endpoint.

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?

'Use it to document webhooks and calls you have only seen in traffic' gives a clear positive usage context, and the note about getting the id from list_requests establishes the prerequisite workflow. It stops short of naming explicit alternatives (e.g. when to prefer add_api_example or upsert_api_endpoint instead), so it is strong but not fully 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?

Annotations already flag destructiveHint=true and openWorldHint=true; the description adds genuinely new context — the external tunnel dependency and the Pro plan gate — plus the fact that payloads are template-generated with provider signatures. It does not explain why the call is considered destructive (i.e., that it delivers a real HTTP request to the user's endpoint), leaving a small gap.

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

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

A single dense paragraph that front-loads the action and the prerequisite, then the parameter options and the plan requirement. Efficient, though the parenthetical provider enumeration duplicates the schema's own 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 covers prerequisites, payload generation and the plan gate, which is most of what an agent needs. It does not indicate what the call returns (delivery status, response body from the localhost endpoint), a minor gap for a tool whose outcome the agent may need to report.

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 all four parameters are already documented, and the description largely restates them (provider list, optional event, body override). Notably it never mentions the required `subdomain` parameter, so it adds little beyond the schema; 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 (send a generated test webhook to the user's localhost) and immediately names the mechanism (tunnel CLI). It is clearly distinguishable from siblings like replay_request or run_api_endpoint, which operate on saved/captured requests rather than synthetic provider payloads.

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 the two modes of use (provider + optional event for a template payload, or a custom JSON body) and the hard prerequisites: tunnel CLI running and Pro plan required. It stops short of explicitly saying when to prefer this over replay_request or run_api_endpoint.

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 mark this as a non-destructive, idempotent write. The description adds value beyond them by disclosing persistence ('Persists on the tunnel') and the exact revert semantics of enabled: false, which the annotations cannot convey. It omits whether the change applies to in-flight requests or requires tunnel reconnection.

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 effect, followed by the example and the revert instruction. 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?

Complete for a two-parameter toggle: what it does, why, persistence, and how to revert. The only gap is operational timing (immediate effect vs. next connection), which is minor but would help an agent reason about sequencing.

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 both parameters are already documented, including the true/false semantics of enabled. The description restates the enabled behavior but adds no syntax or format detail beyond the schema, so 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?

Names a specific verb+resource ('opt a tunnel into a 120-second ingress timeout') and states the exact effect versus the 30-second default. It is unmistakable against siblings like list_tunnels or set_ws_passthrough.

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 a concrete use case ('tool calls that legitimately run long, e.g. an MCP server exposed through the tunnel') and the revert path via enabled: false. It does not explicitly state when not to use this versus the default 30-second behavior, but the intended context 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?

The description adds important behavior beyond the annotations: enabling requires a Pro/Team plan, disabling is allowed on any plan, and the real effect is relaying application-level WebSocket traffic to localhost. It does not explain whether changes take effect immediately or how errors are surfaced, but it adds meaningful 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?

Two sentences, front-loaded with the main action and followed by the plan/disable rule. There is 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?

For a two-parameter toggle with no output schema, the description covers the core effect, plan gating, and reversal path. It could say more about immediate effect or prerequisites, but the essential information for correct invocation is present.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds semantic nuance around the enabled parameter, clarifying plan-gated enabling versus disabling on any plan, which is useful beyond the schema wording.

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 action and target: opting a tunnel into WebSocket passthrough so an application-level WebSocket connection can be relayed to localhost. It distinguishes the tool from sibling tunnel operations by describing the exact toggle behavior rather than general tunnel management.

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 clearly indicates when to use it for relaying WebSocket connections and states the plan requirement for enabling, plus that disabling works on any plan. It does not explicitly name alternative tools, but the context is strong enough for correct 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?

Annotations only declare generic hints (non-read-only, idempotent, non-destructive); the description adds substantive traits: content is read-only for recipients, secrets are hidden, environments are never shown, the collection cannot be exported, and the link is stable across calls. That is real behavioral context beyond the structured hints.

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 tight sentences, each with a distinct payload: scope, disclosure rules, return value, and sharing guidance. No redundancy and the primary action 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?

With 3 parameters, full schema coverage, no output schema, and annotations covering the safety profile, the description fills the remaining gaps: what recipients see, what is withheld, and what the call returns. Nothing needed 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%, so the baseline is 3, but the description adds decision-level meaning: link_access and invite should only be used when the user asks for sharing outside the team. It does not restate the enum values or the 10-invite cap, which the schema already carries.

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 ('Share a whole collection') and immediately scopes it as covering every endpoint including future ones, which cleanly separates it from the sibling share_api_endpoint. An agent can distinguish the two 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?

Gives an explicit default ('with no other arguments it stays restricted to the workspace') and a narrow condition for escalation ('set link_access or invite people only when the user asks to share it outside the team'). It also routes the agent to get_api_collection for retrieving the resulting link.

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?

Adds substantial context beyond annotations: the shared page is read-only and always hides credentials and secrets, `restricted` keeps the URL unchanged, `commenter` requires the Team plan, and invites trigger emails with sign-in. These are real behavioral facts the annotations (readOnly/idempotent/openWorld) do not convey.

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-loads the core action and groups access-level behavior logically. It is somewhat long and the opening sentence is slightly redundant with the title, but every clause carries useful routing 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?

With annotations covering safety and no output schema required, the description covers the creation flow, access modes, and the returned link adequately. It could mention idempotency/upsert behavior on repeat shares, but 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, but the description meaningfully enriches `link_access`: what viewer/commenter grant, the plan requirement, and the sign-in nuance. It adds semantic value over the raw enum.

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 ('Create an endpoint's shareable link and return it'), and the return behavior is explicit. It is clearly distinguishable from sibling get_api_share_link, which reads rather than creates.

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 strong when-to-use guidance, contrasting the default restricted link (PRs/internal messages) against external sharing via `viewer`, `commenter`, or `invite`. It does not name the sibling get_api_share_link or say when to prefer it, so it falls short of explicit alternatives.

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

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

Beyond the annotations (idempotent, non-destructive), the description discloses partial-update semantics, folder auto-creation by name, and optimistic concurrency (stale version rejected) – real behavioral context an agent can't see in the schema. It doesn't say what the upsert returns or how a kind/method mismatch is resolved.

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 identity of the tool and its upsert key are front-loaded, and each following sentence carries a distinct rule (partial update, path syntax, folder creation, version conflict). Slightly dense for five clauses, but nothing is 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 an 11-parameter mutation with no output schema, the description covers the conflict risk, default behaviors, and the trickiest field formats. Only the return value and any constraints on changing collection_id are left implicit.

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 earns above that by explaining path-variable syntax (:id, {id}, {{id}}), that `folder` is created if missing, that `version` must come from get_api_endpoint, and that only sent fields are changed.

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?

"Document an endpoint: creates it, or updates the existing one for the same method + path" gives a specific verb pair, resource, and the upsert key, which immediately separates it from create_api_collection, get_api_endpoint, and delete_api_endpoint.

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 says when to use it ("whenever you add or change a route in the code") and points at the read-side sibling by naming get_api_endpoint as the source of `version`. It stops short of explicit exclusions, e.g. when to edit via a proposal or when import_api_spec is the better path.

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