Porch

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: exactly what is destroyed (all captured requests) and what is preserved (URL, key, response settings). It stops short of stating irreversibility or auth requirements, so it is not 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 short sentences, zero waste, with the destructive action and the preserved state front-loaded in that order. Nothing extraneous.

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 destructive tool with an output schema and full annotation coverage, the description says enough to call it correctly. The only meaningful omission is whether the deletion is recoverable, which the destructiveHint only partially covers.

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?

Single parameter with 100% schema description coverage, so the schema already explains inbox_key and its "porch_sk_" format. The description adds nothing parameter-specific, which is the correct baseline when the schema does the work.

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 ("Delete all captured requests from the inbox") and immediately scopes it against the sibling delete_inbox by clarifying that the URL, key and response settings survive. An agent can distinguish this from deleting the inbox itself 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?

Usage is implied by the scope statement — clear the captured requests while keeping the inbox configuration — but the description never says when to prefer this over delete_inbox or list_requests, nor mentions any prerequisite or confirmation step. Adequate but no explicit 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?

Annotations only declare the generic safety profile (not read-only, not idempotent, not destructive). The description adds genuine behavioral facts an agent could not infer: link previews and email scanners cannot answer, only a button press counts, only the first answer is accepted, and page opens are not recorded.

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: the purpose first, the anti-false-positive guarantee second, the mandatory next call last. No filler and no 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?

With an output schema present, return values need not be described, and annotations cover the safety profile. What remains — what the recipient sees, how answers are captured, and the required wait_for_approval follow-up — is all present, so an agent has everything needed 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 coverage is 100% and each property carries its own description (title, choices with default, message, inbox_key origin), so the schema does the heavy lifting. The description's 'your title, message and one button per choice' largely restates what the schema already says, so the baseline 3 applies.

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

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

States a concrete verb+resource ('Make a link') and immediately scopes it ('to send a person when you need their decision'), then explains what the link renders. An agent can distinguish this from create_inbox or set_response without opening any schema.

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

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

Gives a clear trigger condition ('when you need their decision') and explicitly names the required follow-up step: 'Then call wait_for_approval.' It is not fully specified as when-not-to-use guidance (e.g., it never contrasts with set_response for programmatic answers), but the sequencing guidance is unusually actionable.

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

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

Annotations mark it as a non-read-only, non-idempotent, non-destructive creation. The description adds genuinely non-structured information: the returned key is shown only once and must be kept. It doesn't mention retention beyond schema (TTL/inactivity deletion live in the schema), so it's not 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 concrete thing the caller receives (URL plus key), followed by use cases and the one-time key warning. 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?

An output schema exists so return values need not be spelled out, and annotations cover safety. The description covers the critical one-time-key caveat and use cases; only a pointer to lifecycle management (delete_inbox/get_inbox) is missing, which is minor.

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?

Only one parameter, and the schema documents ttl_minutes at 100% coverage including default, range, and the 240-minute inactivity deletion rule plus the 'pick the shortest' guidance. The description adds nothing further about parameters, 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+resource (create an inbox that yields a public URL and inbox_key) and immediately says what the URL does: records every HTTP request sent to it. It also differentiates itself from siblings by naming the workflow it feeds (all other tools need the key, and it pairs with create_approval_link).

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 contexts for use: webhook endpoint, OAuth redirect URI, job callback URL, or with create_approval_link. It doesn't state when *not* to create an inbox (e.g. reuse an existing one via get_inbox instead of minting a new key), so it falls short of 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new outcome detail beyond the annotations: the inbox URL returns 404 and the inbox_key becomes invalid, which tells the agent the deletion is effectively irreversible.

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, no filler, and the destructive outcome is front-loaded rather than buried. Every clause carries information an agent needs before calling a delete.

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?

An output schema exists, so return values need not be explained, and the description covers the irreversible consequence of the call. The only gap is the absence of prerequisite/authorization context, though openWorldHint=false and the annotation set largely frame the 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?

Only one parameter, and the schema already carries a 100% coverage description including the 'porch_sk_' prefix origin. The description adds nothing about inbox_key, so the baseline 3 applies when the schema does all the work.

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?

'Delete the inbox and everything it captured' states a specific verb plus resource and quantifies the blast radius (the inbox and all captured content). It is unmistakably distinct from create_inbox, get_inbox and clear_requests, which cover other lifecycle stages.

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 no when-to-use or when-not-to-use guidance and never mentions the neighboring clear_requests tool, which removes requests without destroying the inbox. An agent must infer the decision criteria from the tool name alone.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds a quick summary of the returned inbox fields, but since an output schema exists and no additional behavioral context (auth, errors, pagination) is provided, it adds only modest value beyond the structured fields.

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

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

The description is a single front-loaded sentence with no filler. It states the action first and then efficiently lists the returned attributes.

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

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

Given the tool's low complexity, complete annotations, 100% parameter schema coverage, and an output schema, the description is nearly complete. It could mention error cases such as an invalid or expired inbox_key, but that is a minor gap for a read 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%, and the single parameter inbox_key is well documented in the schema, including its origin from create_inbox and its prefix. The description adds no extra detail about the parameter, so the baseline of 3 for high schema coverage 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 uses a specific verb ('Show') with a clear resource ('inbox') and enumerates the returned fields (URL, expiry, request count, etc.), which distinguishes it from siblings like get_request or list_requests. It stops short of explicitly naming an alternative, 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?

There is no when-to-use guidance, no prerequisites, and no mention of when not to use it versus alternatives such as get_request or list_requests. The usage is only implied by the tool name and the listed return fields.

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 establish the safe read profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value beyond that: body encoding rules (UTF-8 text or base64), the byte-exact curl/fetch recipe produced by replay_to, and a security warning to treat contents as untrusted input.

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 no filler. The core return contract is front-loaded, the optional replay behavior follows, and the safety warning closes it out — every sentence earns its place.

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

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

An output schema exists, so return values need not be documented, yet the description still summarizes them helpfully. With annotations covering safety and full schema coverage on inputs, nothing an agent needs to call this 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 genuine meaning for replay_to — it explains that it yields a byte-exact curl command and fetch recipe for targets Porch cannot reach. The remaining parameters are left to the schema, which is adequate but no bonus.

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 ('Full details of one captured request') and enumerates exactly what is returned: method, path, parsed query, headers, body encoding, and json/form parsing. This clearly distinguishes it from the sibling list_requests, which enumerates rather than returns full detail for a single request.

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 conditional guidance for the optional replay_to path: use it when the target is somewhere Porch cannot reach, with 'localhost' as a concrete example. It does not explicitly state when to prefer get_request over list_requests, so it stops short of full when/when-not/alternatives coverage.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: sort order, the paging/default-window semantics of 'after', and the explicit side-effect disclaimer regarding wait_for_request's position.

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

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

Four short sentences, each carrying distinct load: purpose, paging behavior, sibling routing, and side-effect disclaimer. The essential scope and ordering appear up front 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?

Output schema exists so return shape needn't be documented. Ordering, paging, filtering parameters (covered by schema), sibling alternative, and non-interference with wait_for_request are all addressed, leaving nothing an agent needs to call this 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. The description nonetheless adds meaning the schema lacks, namely what happens when 'after' is omitted (most recent requests are returned) versus when it is supplied, which is the key semantic distinction for this 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 ('List captured requests as summaries') plus result granularity and sort order ('oldest first'). It also explicitly contrasts with the sibling get_request, which returns headers and body, so the agent can distinguish the two without opening schemas.

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

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

Gives explicit routing ('Use get_request for headers and body') and spells out the paging condition: no 'after' means most recent, with 'after' means page forward from that id. It further clarifies the tool does not move wait_for_request's position, resolving a likely coordination question with a sibling.

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 the mutation/idempotency profile, and the description adds traits the annotations cannot express: pages render in a browser sandbox where scripts and forms do not run, and reset:true restores the default. It omits permission/auth requirements and what happens to in-flight requests, but the sandbox constraint is real added value.

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 purpose, then use cases, then the sandbox caveat and reset. Every sentence carries information; nothing is 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?

With an output schema, full parameter coverage, and annotations present, the description supplies the remaining decision-relevant context: what it configures, why you'd use it, and the sandbox limitation. Only auth/permission expectations and failure behavior 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 schema already documents body size, status range, header shape, path_prefix matching, and reset semantics. The description's mentions of reset and headers largely restate schema text, adding only the framing of inbox-wide vs sub-path application — baseline 3.

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

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

States a precise verb+resource ('Choose what Porch sends back to callers') plus the exact scope (whole inbox or a sub-path) and the configurable surface (status, headers, body). This is unmistakably distinct from every sibling, all of which read or manage requests/inboxes rather than shape the reply.

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 when-to-use scenarios (webhook verification handshakes, OAuth redirect landing page, 302 with Location header) and the reset escape hatch. It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it is clear context without 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?

Annotations declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered, but they say nothing about blocking. The description adds the genuinely useful traits: this is a long-blocking call, it short-circuits when already answered, and a timeout does not end the approval. It could also state whether the person must authenticate before answering.

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 zero filler, front-loading the blocking semantics before the two edge-case rules. Every sentence carries a distinct 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?

An output schema exists, so return-value shape need not be explained, and the description covers the two behaviors an agent most needs (immediate return, retry after timeout). It leaves open whether the timeout is caller-configured elsewhere and what condition distinguishes a timeout result from an answer.

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 documented by the schema itself; the description adds no syntax or format detail for path, inbox_key or timeout_seconds. 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 and resource: it blocks on an approval link and returns the person's choice. That is concrete and distinct from most siblings. It does not, however, differentiate itself from the very similar sibling wait_for_request, leaving that distinction to 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 operational guidance: it returns immediately if the answer already exists, and the caller should re-invoke it after a timeout. That is actionable when-to-call behavior. It stops short of saying when to prefer this over wait_for_request or how to interpret a timeout result.

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 write-safety profile; the description adds the behaviors that matter here — blocking, timeout default/max, the timed_out: true signal on expiry, cursor advancement so arrivals between calls are not missed, and replay-before-first-call semantics. One wrinkle: it says max 300 while the schema's maximum is 3600, a constraint mismatch worth noting.

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, then default cursor semantics, then timeout/retry. No filler and no restating of the title or schema.

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

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

Output schema exists and the description correctly points to get_request for the return shape, and the timeout/cursor model is covered. It does not say whether a returned request is also still retrievable via get_request, or how concurrent waiters interact with the shared position — the main remaining 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?

Schema coverage is 100%, so the baseline is 3. The description goes beyond it by clarifying that the saved cursor is scoped to "this inbox and these filters," which explains how method/path_prefix interact with the default position — meaning the schema alone does not 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 and resource ("Block until a request arrives, then return it in full") and anchors the return shape to a named sibling (get_request), so an agent can tell it apart from the passive reads. The blocking wait semantics are 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?

Explains the default behavior (next not-yet-returned request for this inbox and filters) and prescribes the follow-up action ("call it again to keep waiting"), which tells the agent how to run the polling loop. It never excludes alternatives explicitly, e.g. when to use get_request or list_requests instead of blocking.

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