Ledgerbell onchain alerts

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

With only openWorldHint in annotations, the description adds the cost signal ('Free') and the enum of watch kinds, which is genuinely useful. It does not disclose what happens after creation (delivery semantics, webhook retry, whether watches can duplicate) or any permission requirements beyond the API key.

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, all front-loaded, no filler; the kind enumeration and the conditional event/token rules are stated compactly. Every sentence carries information an agent needs to invoke the tool.

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 8-parameter creation tool with no output schema, the description covers the tricky conditional parameters well and signals cost. Remaining gaps (chain semantics, label format, post-creation behavior) are minor given the schema carries chain as an enum.

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 low (38%) and the description compensates substantially: it defines the kind enum values, states that event requires a signature or topic0 for kind=event, and explains that token is wallet-kind-only while label is optional. It still leaves chain and label unelaborated, but it adds real 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 opens with a specific verb+resource ('Start watching an address') and the title clarifies the webhook-alert effect, so an agent knows this creates a subscription. It is distinguishable from delete_watch/list_watches/test_watch by the 'Start' framing, though it never names them 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?

It gives conditional parameter guidance ('For kind=event pass event as a signature...', 'wallet kind: only this ERC-20') which implies when each mode applies. However, there is no explicit when-to-use-this-vs-alternatives guidance, e.g. no mention of when to call test_watch first or how this relates to list_watches.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses a payment requirement and mechanism ('$1 USDC per call via x402 (Base)'), the create-vs-extend branch, and that repeat calls stack duration. It omits failure/refund behavior and what happens if payment fails, but the economic and state-transition behavior is unusually well surfaced.

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?

One dense but front-loaded sentence that leads with the core action and branches, then lists entitlements, then price. Every clause carries information, though the colon-separated feature list makes it slightly heavy for a single sentence.

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 annotations and no output schema, the description covers the essential call semantics: what is granted, key-or-create behavior, repeat-call extension, and cost per invocation. The main remaining gap is whether a key is returned and how payment/errors are surfaced.

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

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

Schema coverage is 100% and the single param is already described as optional in the schema, which sets a baseline of 3. The description adds genuine meaning beyond it by specifying the consequence of omission: a brand-new Pro key is minted instead of extending an existing one.

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 ('Adds 6 days of Pro to the given key') plus the exact entitlement quanta granted (30 watches, 1,000 alerts/day, safe tx alerts, proxy-upgrade reports). The purchase/extend purpose is clearly distinct from the watch-management siblings (add_watch, list_watches, etc.).

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?

'Call again to extend' tells the agent how repeat invocations behave, and the parenthetical explains the no-key case. It gives clear operational context but offers no explicit when-not-to-use or alternative-tool routing (arguably none exists among the siblings).

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

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

With no annotations, the description carries the full burden and does disclose a genuinely important trait: the key cannot be recovered and is the only credential for watches, which tells the agent this is an irreversible secret issuance. It omits whether the key value is returned in the response and any rate or plan limitations on key creation.

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 the core action front-loaded and the critical warning placed immediately after. The standalone 'Free.' at the end duplicates 'free-plan' and is the one sentence that does not earn 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?

For a creation tool with no output schema, the most important missing detail is whether the generated key is returned in the response body — the description says 'Save it' but never says where the agent will receive it. Combined with the absent usage prerequisites, the definition is adequate but leaves a real operational 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a param-less schema applies. The mention of 'free-plan' usefully explains why no plan argument exists.

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 free-plan API key'), which is clearly distinguishable from the watch-oriented siblings (add_watch, list_watches, etc.). The trailing 'Free.' restates the plan tier already given in the first sentence, adding slight redundancy rather than new precision.

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 only implied: the reference to 'your watches' hints that this credential is needed before creating or managing watches, but the description never says when to call it versus other tools or whether it is required setup. There are no explicit exclusions or prerequisites 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?

The destructiveHint=true annotation already flags this as a destructive operation, so the description's job is smaller. It adds two pieces of real context the annotation lacks: that the operation halts the watch first ('Stop and delete') and that it costs nothing ('Free'). It says nothing about irreversibility, auth requirements, or failure modes beyond what the annotation covers.

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, front-loaded sentences with no filler; the mutation verb leads and the cost note trails. It is efficient, though the extreme brevity borders on under-specification rather than pure conciseness.

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 destructive, irreversible-looking operation with two required parameters and no output schema, the description omits the most important detail: what deleting a watch destroys and whether it can be undone. The undocumented 'id' parameter is also unaddressed, so an agent lacks enough to invoke confidently.

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 only 50%: the 'key' parameter is documented in the schema, but 'id' — the watch identifier — has no description anywhere. The description does not compensate at all, adding no guidance on what form 'id' takes or where to find it. With sub-80% coverage the burden was on the description and it does not meet it.

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

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

'Stop and delete a watch' gives a specific verb pair and resource, so the agent knows exactly what happens. It does not distinguish itself from siblings like add_watch or list_watches, but those are self-evidently complementary. Clear but undifferentiated.

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 statement of when to use this versus list_watches or test_watch, and no prerequisites or exclusions. 'Stop and delete' hints at the use case but leaves the agent to infer everything else.

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?

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description adds that the call is free and that it returns plan tier, limits, and today's alert count, which is genuine behavioral context beyond the annotation, but it says nothing about pagination or rate limits.

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

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

A single front-loaded sentence that enumerates the payload, followed by a one-word cost flag. Compact and waste-free, though the 'Free.' fragment is slightly abrupt.

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 names the returned data (plan, limits, alerts today, watches), which is what an agent needs to decide the call is worthwhile. Only missing element is pagination or result-size behavior.

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

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

Schema description coverage is 100% and there is a single parameter, so the schema already documents the key fully; the description's 'for a key' adds no syntax or format detail. Baseline 3 is appropriate 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 (Show) and enumerates the resources returned: plan, limits, alerts today, and all watches for a key. It clearly contrasts with the add/delete/test siblings by being the listing variant, 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?

There is no guidance on when to use this versus add_watch, delete_watch, or test_watch, and no prerequisites beyond the required key. The lone hint is 'Free,' which signals cost but not selection criteria.

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

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

With no annotations the description carries the full behavioral burden. It does disclose two genuinely useful facts beyond the schema, the 5-per-hour rate limit and that the call is free, but it omits whether the webhook receives a real vs. synthetic payload, whether quota is shared with real alerts, and what failure looks like.

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

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

Front-loaded with the action, then two parenthetical facts (rate limit, cost). Very tight with no filler, though the 'Free.' fragment is telegraphic and could have been folded into a clause that also conveyed a behavioral detail.

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

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

A side-effecting tool with no annotations, no output schema, and two required parameters warrants more than one sentence: auth expectations, quota-exceeded behavior, and what the test alert actually delivers to the webhook are all absent, leaving an agent unable to call it confidently.

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 only 50%: 'key' is documented in the schema as the Ledgerbell API key, but 'id' has no description at all and the description only weakly implies via 'a watch's webhook' that it is the watch identifier. The description adds essentially no explicit parameter meaning to compensate for the gap.

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?

Clear specific verb+resource: send a test alert to a watch's webhook. It is readily distinguishable from add_watch/delete_watch/list_watches by the 'test alert' framing, but the description never explicitly contrasts itself with those siblings or says whether the test alert is a dry-run that does not persist.

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 purpose implies a testing scenario, but there is no explicit when-to-use statement, no prerequisite (e.g. that a watch must already exist), and no mention of what to do if the 5-per-hour quota is hit. Rate-limit and cost facts are behavioral, not usage guidance.

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