Hookden

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

With no annotations, the description carries the full burden and does well: it discloses the return value (public capture_url), storage behavior (any method, any subpath, headers + raw body), retention (~24h for anonymous bins), and auth requirements (no auth needed). It doesn't mention rate limits or response details beyond the URL, but the key behavioral traits are covered.

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

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

Three sentences, front-loaded with the core purpose. Each sentence earns its place: creation and return value, capture behavior, retention/auth, and follow-up tools. No fluff or repetition.

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

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

Given this is a parameterless creation tool with no output schema, the description is complete: it explains the return value, how to use it, storage semantics, retention, and next actions. An agent can confidently invoke it without needing additional details.

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

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

The tool has zero parameters and the schema coverage is 100%, so the baseline is 4. The description adds useful context about what the returned capture_url is for, even though there are no parameters to document.

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 a new webhook capture bin.' It clearly distinguishes itself from the sibling read/test tools by describing what the tool produces (a capture_url endpoint) rather than what it reads or verifies.

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?

Clearly implies when to use: when you need a new endpoint to receive webhooks. It also instructs the agent on the next step after creation ('Then read what arrived with list_captures, get_capture, or wait_for_capture'), but doesn't explicitly describe when not to use it or compare trade-offs with the 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?

With no annotations to rely on, the description carries the burden and does so well: it discloses that the full request is returned, that binary bodies are base64-encoded, that there is an 8KB limit, and that a URL is provided for raw bytes. This gives an agent accurate expectations about response format and size constraints.

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

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

Two tight sentences, front-loaded with the core purpose, followed by a useful caveat about binary bodies. 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?

The tool is simple: fetch one captured request by id and bin. The description covers what is returned, how binary bodies are handled, the size limit, and the raw-byte URL. Given the absence of an output schema, this is enough for an agent to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description doesn't need to add param semantics because the input schema already documents 'id' and 'bin' clearly, including where the id comes from. The description adds no extra parameter-level detail, but it isn't necessary.

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 ('Get'), identifies a precise resource ('one captured request'), and enumerates what is included: method, path, query, headers, and body. It also distinguishes itself from sibling tools like list_captures and wait_for_capture by focusing on full retrieval of a single capture.

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 clearly signals the tool is for retrieving one full capture rather than listing or waiting for captures, and the schema's id description explicitly references list_captures / wait_for_capture as the source of the id. It lacks an explicit 'use vs. alternative' statement, but the context is clear enough.

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

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It does well by stating the ordering (oldest first), the summary fields returned, and the filtering behavior of 'after.' This is more transparent than a minimal description, though it does not detail error cases or potential side effects, which are unlikely for a list operation.

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

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

Three sentences with no filler. The main purpose is front-loaded, followed by the summary format, the routing to get_capture, and the 'after' parameter behavior. 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?

Even without an output schema, the description identifies the key return fields, making the output format clear. It also points to the tool for full details when needed. Combined with a fully documented schema, the definition is complete for an agent to invoke correctly.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds a brief explanation of 'after,' but it largely restates the schema's meaning, adding little new semantic value.

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

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

The description starts with a specific verb and resource: 'List requests captured by a bin, oldest first.' It also differentiates itself from get_capture by noting it returns compact summaries rather than full headers/body, so an agent can distinguish it from its sibling 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 explicitly says 'Use get_capture for full headers/body,' giving a clear condition for choosing the alternative tool. It also implies when list_captures is appropriate: when compact summaries are sufficient.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well: captures are 'marked as simulated,' they 'never count as real webhook traffic,' the default payload is a GitHub push event, and the tool returns the capture 'in full.' It does not cover failure behavior or idempotency, but the core behavioral contract is clear.

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

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

The description is front-loaded with the core purpose and scoped benefit, then gives concrete examples, then closes with an important behavioral caveat. Every sentence earns its place; nothing is redundant or filler.

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

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

For a simple two-parameter tool with no output schema, the description is complete: it explains the return value, the default behavior, the example options, and the simulated nature. An agent has enough to call this correctly and interpret the result without needing additional context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining that 'bin' comes from create_bin and by giving concrete example slugs for the 'example' parameter, plus the default behavior. This makes both parameters more actionable than the schema alone.

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

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

The description uses a specific verb and resource: 'Simulate a webhook delivery into a bin.' It clearly distinguishes this from sibling tools by noting it requires no external sender and seeds a sample capture, making it unambiguous against list_captures, get_capture, and set_response.

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

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

The description provides a clear usage context and even maps the full workflow: 'create_bin → send_test_webhook → list_captures / get_capture.' It explains why to use this tool (to exercise the loop entirely from MCP) and notes that simulated captures never count as real traffic. It does not explicitly say when not to use it, but the context is strong.

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

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

With no annotations provided, the description carries the full burden, and it does well. It discloses that the operation is a partial update ('Only the fields you pass change; everything else keeps its current value') and that the incoming request is still captured 'in full either way.' It also explains the per-request template rendering behavior, which is a non-obvious side effect. It stops short of describing error cases, rate limits, or what the mutation returns, so a small gap remains.

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 longer than average, but every section earns its place: a crisp first sentence, template rule, provider examples, partial-update semantics, and client restriction. It is front-loaded with the core purpose and uses examples to make a complex feature concrete. The only minor issue is the provider list could be trimmed, but it does add practical value for an agent handling verification handshakes.

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

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

Given the tool's complexity (templating, partial updates, header restrictions) and the absence of annotations/output schema, the description is quite complete. It covers what to configure, the template mechanism, how partial updates behave, and that capture is unaffected. It doesn't mention the API response format, but since no output schema exists and the mutation semantics are clear, this is acceptable. A 5 would require explicit error handling or privilege details.

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 an extra point by enriching parameter meaning: it explains how body and header templates work with concrete examples (Slack, Zoom, Meta, Strava, Asana) and highlights that delay is for testing sender timeouts/retries. This goes beyond the schema's basic 'templates allowed' phrasing and helps an agent construct realistic values.

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

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

The description opens with a specific verb ('Configure') and resource ('what a bin replies to webhook senders'), then enumerates the exact knobs: HTTP status, content-type, body, headers, delay. It clearly distinguishes itself from sibling tools like create_bin, get_capture, or send_test_webhook by focusing solely on mutating a bin's response behavior. An agent can immediately know what this tool does and why it exists.

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 strong context for when to use this tool: after creating a bin (via create_bin) and when needing to configure responses, especially provider verification handshakes. It includes a prerequisite ('bins created via create_bin by this same client') and clarifies that the incoming request is still captured, which helps avoid confusion with capture-related tools. However, it does not explicitly name alternatives or state when *not* to use it, leaving some inference to the agent.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the secret is used only in-memory and never stored or logged, that no bin is needed, and that failures often stem from re-serialized bodies. This is strong behavioral context for a verification tool, though it stops short of specifying whether the operation is network-free or the exact return 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?

The description is one compact paragraph that front-loads purpose, then scope, then inputs, then the security guarantee, then a troubleshooting pointer. Every sentence earns its place; there is no filler or repetition of schema content.

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

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

With no output schema, the description conveys the outcome via 'computes ✓/✗ badges' but doesn't explicitly state the return format. It covers supported schemes, required inputs, the body exactness gotcha, and the no-storage guarantee, which is fairly complete for a tool of this complexity. The only notable gaps are an explicit return-type statement and mentioning get_capture as the retrieval step after create_bin.

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 covers all parameters with descriptions, so the baseline is 3. The description adds value by stressing the byte-exact body requirement, which is critical for signature algorithms, and by grouping the 25 enum schemes into algorithm families. It complements rather than repeats the schema's detailed parameter descriptions.

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

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

The description opens with a specific verb-resource pair ('Verify a webhook signature against a secret') and enumerates the scheme families (HMAC-SHA256, ECDSA, RSA, HMAC-MD5). It distinguishes itself from bin/capture siblings by saying 'No bin needed' and 'the same engine that computes badges on captures', so an agent can tell it apart without opening the schema.

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

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

It gives an explicit how-to: pass the scheme, the secret, the delivery's headers, and the byte-exact raw body. It also names create_bin as the alternative when verification fails due to a re-serialized body, providing a concrete choose-other-tool rule. It doesn't enumerate exclusions for every sibling, but the guidance is clear and actionable.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly explains the blocking behavior, timeout handling, and the timed_out:true return instead of an error. This goes beyond the schema and gives the agent important expectations about how the tool behaves.

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

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

The description is compact and front-loaded with the core behavior, then the ideal flow, then the timeout edge case. Every sentence contributes meaningful information without redundancy or filler.

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

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

Given no output schema, the description explains the key return behavior (full capture or timed_out:true) and timeout semantics. It could say a bit more about error conditions or the exact shape of the returned request, but the essential invocation context is covered.

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 description adds a useful paraphrase about after_id (waiting for the next capture after 'now'), but it does not materially expand on the schema's parameter documentation.

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

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

The description states a specific action (block until next request arrives) on a specific resource (a bin) and clarifies the return behavior. It clearly distinguishes this tool from siblings like get_capture and list_captures, which retrieve existing data rather than waiting for new data.

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

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

The description provides an explicit ideal flow: create_bin → configure webhook sender → trigger it → wait_for_capture, which gives clear operational context. It does not explicitly name alternative tools or state when not to use this one, but the intended sequence is clear enough for an agent.

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