Datoka Hooks

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

Goes well beyond the annotations: it clarifies the return is a deliveryId and not proof of delivery, that the free allowance is 100 events/day per receiver with credits consumed beyond that, and that identical bytes are required under a reused eventId. Annotations cover the safety/idempotency profile, and the description adds quota, retry, and delivery-semantics context that the annotations do not.

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, front-loaded with the action and payload bound, then retry/quota behavior. Dense but every clause carries an operational constraint; 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?

With no output schema, the description correctly explains what comes back (deliveryId, not delivery proof), how to observe real delivery (poll get_hook_delivery), quota/credit implications, and retry idempotency. 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%, so the baseline is 3, but the description adds real meaning: the 65536-byte payload ceiling, the retry invariant tying eventId to exact bytes, and the role of the token as a delivery credential. It stops short of explaining contentType encoding rules, which remain schema-only.

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 with scope: enqueue payload bytes for a previously verified receiver via its delivery token. It is clearly distinguishable from siblings like register_destination or purchase_hook_credits, and the '(receiver)' qualifier pins down what is being acted on.

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 operational flow: reuse eventId and exact bytes on retries, then poll get_hook_delivery, and rules out supplying an arbitrary destination. It names a follow-up sibling but does not contrast against other siblings (e.g., verify_hook_receipt) or state when this tool should not be called.

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 annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description adds useful scope exclusions ('No activation or delivery') that clarify what the read does not do, though it does not describe return format or token-handling details.

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

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

The description is three short, front-loaded sentences with no wasted wording. The core read operation, scope exclusions, and usage timing are all presented efficiently.

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 status tool with no output schema, the description covers the operation, when to call it, and what it does not do. It only partially indicates what the returned status/challenge contains, which is a minor gap rather than a blocking omission.

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 are fully documented in the schema itself. The description repeats that the management token is used for the read but adds no format, syntax, or edge-case meaning 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?

The description states a specific read operation over a precise resource: the existing hook ownership challenge and verification/revocation status. It also explicitly distinguishes the tool from get_hook_delivery and from activation/delivery actions, so an agent can tell it apart from siblings 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?

It gives explicit timing guidance ('Use after registration or an interrupted verification') and names an alternative tool with its own condition ('use get_hook_delivery for one accepted event'). This directly answers when to use this tool versus 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 already cover readOnly, idempotent and non-destructive, so the bar is lower; the description adds real behavioral context by noting the management token is required, that the call is free, that it does not purchase credits, and that the daily free allowance is tracked separately. It does not cover rate limits or failure modes, which keeps it from a 5.

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

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

Four short, front-loaded sentences, each carrying distinct information: purpose, safety/free status, alternative tool, and the separate free allowance. No filler or repetition.

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

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

No output schema exists, but the description states what is returned conceptually (remaining purchased credits) and clarifies it excludes the daily free allowance. It could say more about the response shape or behavior for invalid/unknown hooks, but it is complete enough to call 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 both parameters are fully documented with patterns and semantics in the schema, so the baseline of 3 applies. The description adds only the implicit constraint that the hook must already exist; it contributes nothing new about hookId or managementToken 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 and resource (read remaining purchased admission credits) and scopes it precisely to an existing hook via its management token. It explicitly separates paid credits from the daily free allowance and distinguishes itself from purchase_hook_credits, so an agent can tell it apart from siblings 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?

The description clearly frames the use case (check credits, free and read-only) and routes to purchase_hook_credits for purchasing/quoting, giving an explicit when-not. It lacks an explicit trigger condition for calling this versus other read tools, so it falls just short of a full 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely non-derivable behavior: polling semantics and the important caveat that signed observations attest relay attempts, not successful business processing by the receiver. That semantic limit is exactly the kind of context annotations cannot express.

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, front-loaded with the core action and the key read/poll distinction. Each sentence carries non-redundant meaning (scope, usage, semantic caveat, no-side-effect guarantee), though the phrasing is slightly dense.

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 3-parameter tool with no output schema and strong annotations, the description covers the important ground: what it reads, when to call it, the statuses it resolves, and the limit on what a signed observation proves. Return-field detail is absent, but with 100% schema coverage and rich annotations that is a minor gap.

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 token, hookId and deliveryId are already fully documented in the schema, including pattern constraints and the note that acceptance does not mean delivered. The description restates deliveryId and the token but adds no syntax or format detail 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: read one accepted event keyed by deliveryId plus hook token. It distinguishes itself from accept_hook_event by positioning itself as the follow-up read/poll step, so an agent can tell the two apart without touching either schema.

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

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

It gives clear usage context: poll after accept_hook_event to distinguish queued, retried and completed deliveries. It also rules out side effects ('No new delivery or payment'). It stops short of naming an explicit alternative sibling (e.g. verify_hook_receipt) or when not to use it, so it is clear context but not full routing guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds non-obvious retry semantics: reuse the purchaseId and the same payment payload after any timeout. It doesn't spell out auth/permission details beyond what the schema's managementToken field already says.

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, with the quote-vs-purchase distinction front-loaded and the retry rule following. Every clause carries information an agent needs.

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 nested-payload payment tool with no output schema, the description covers the two invocation modes and retry behavior. It does not say what a quote response versus a purchase response looks like, which is a minor gap given no output schema exists to carry that.

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 and the schema already documents hookId, purchaseId, managementToken and payment. The description adds genuine meaning on top by clarifying the retry relationship between purchaseId and payment and that payment may be omitted.

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 with two distinct modes: request an x402 quote without payment, or buy credits with a signed payment. That is enough to separate it from get_hook_credits, but it never names a sibling tool, so it falls short of a 5.

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

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

It gives clear conditional guidance: omit payment to get a quote, supply a signed payment to buy, and reuse purchaseId plus the same payment after a timeout. It doesn't point at alternatives (e.g., get_hook_credits for balance checks), so no exclusions are stated.

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

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

Adds substantial behavior beyond annotations: what is returned (hookId, private credentials, ownership challenge), the post-state (delivery remains inactive until verification), and a security constraint (keep recoveryKey secret). This complements the idempotentHint without contradicting it.

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 outcome is front-loaded in the first sentence, the workflow follows, and the recoveryKey caveat closes. Every clause carries operational information 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?

With no output schema, the description compensates by describing the return payload and the inactive-delivery state, and it links the call to its required successor tool. Nothing needed to invoke or recover this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds relational semantics the schema cannot: recoveryKey must be reused with the identical target and must not change across a retry. It does not add format detail, so it stops short of a 5.

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 ("Register an HTTPS receiver you control") and immediately distinguishes itself from the sibling verify_destination by naming the follow-up call. An agent can tell this is the registration/onboarding step, not the verification step.

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

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

Gives explicit sequencing (publish the exact challenge on your origin, then call verify_destination) and an explicit anti-pattern (do not register again with a new key; reuse recoveryKey with the identical target after interruption). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false; the description goes well beyond them by disclosing the exact blast radius: new submissions rejected, in-flight accepted deliveries allowed to finish, queued events NOT cancelled, and irreversibility. This is precisely the post-annotation detail an agent needs before calling a destructive tool.

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

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

Four short sentences, zero filler, front-loaded with the action and its hard precondition, then the consequences, then the alternative. Every clause (delivery finish behavior, queued-event caveat, irreversibility) carries distinct decision-relevant 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?

No output schema exists, so the description must cover outcomes, and it does: acceptance behavior for new vs in-flight vs queued events and irreversibility. Combined with annotations covering safety/idempotency and a 100%-documented 2-param schema, nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, with both hookId and managementToken fully documented including patterns and provenance, so the schema carries this dimension. The description only echoes the token requirement ('with its management token') and adds no format or sourcing 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?

States a specific verb and resource (permanently revoke this hook/destination) with the required authorization artifact (management token) and the owner-approval precondition. An agent can distinguish it from get_destination_status, verify_destination, and register_destination without opening any schema.

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

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

Explicitly routes the agent: 'Use get_destination_status first if you only need to inspect access,' naming the read-only alternative by name and the condition that selects it. It also states the operational precondition ('after explicit owner approval'), which is a real gating rule rather than generic advice.

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 real context beyond the annotations: the management token is required, the call does not deliver an event, and activation is conditional ('when valid'). The annotations already cover safety shape (idempotent, non-destructive, open-world), so the remaining gap is failure behavior when the challenge is invalid, which is not described.

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 the action, followed by the prerequisite and the alternative. No filler or restatement of the title.

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 mutation tool with no output schema, the description supplies the prerequisite ordering, the postcondition (no event delivered), and the sibling to use for read-only inspection. Error handling for an invalid challenge is the only notable omission.

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 hookId and managementToken are already fully documented in the schema; the description only echoes the management-token requirement. The 'exact challenge' referenced is not itself a parameter, so it adds workflow meaning but not parameter semantics. Baseline 3 is correct.

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 (verify/activate) and resource (destination), and distinguishes itself from register_destination (the prerequisite) and get_destination_status (the non-activating alternative). An agent can place this tool in the workflow 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 an ordered prerequisite ('First publish the exact challenge returned by register_destination'), a near-exclusion ('does not deliver an event'), and a named alternative ('Use get_destination_status to inspect progress without activation'). This is explicit when-to-use and when-to-use-something-else 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 a safe, idempotent, non-destructive read, so the safety profile is covered. The description adds genuinely non-obvious semantics: the token requirement, the no-send behavior, and the caveat that a valid signature attests relay observations rather than business truth or exactly-once processing.

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 with no filler; the core action and its input source are front-loaded, and each remaining sentence adds a distinct constraint or caveat.

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 should ideally hint at the verification result, which it only does implicitly. Otherwise it is complete: inputs, prerequisite token, source of the artifacts, and the meaning of a passing signature are all covered for a read-only verification tool.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the token, hookId patterns and the 'preserve all fields' instruction. The description reinforces the token requirement and the 'unchanged' constraint on event and receipt but adds little syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (verify/check) and resource (hook receipt plus the event it covers), and pins the inputs to a named sibling, get_hook_delivery. An agent can distinguish this from accept_hook_event (which sends events) without opening either schema.

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

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

Explains the workflow context: it consumes the unchanged event and receipt returned by get_hook_delivery and requires the delivery token. It also states what it does not do ('does not send an event'), implicitly steering event submission to accept_hook_event, though no other sibling is named as an alternative.

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