thePaymentsNotes Ledger

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

Goes well beyond the annotations, which only cover the read-only/idempotent/open-world safety profile. It adds concrete operational constraints: 3 scans per caller per day, 50 per day overall shared with the website, 24h result caching, public-pages-only access, explicit non-certification/audit/legal-advice disclaimers, and enumerated scan_interrupted reasons (timeout, blocked, dns_tls, robots_disallowed, refused, http_error).

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?

Purpose is front-loaded, which is good, but the body is a single bloated paragraph dumping every report field, plus a trailing newsletter link that does not earn its place. Since no output schema exists the field list has some value, but the structure is a run-on enumeration rather than organized sections.

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

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

With no output schema, the description carries the full documentation burden for return values and does so thoroughly: report fields, band values, archetype fallback, gap/actions shape, ledger, checks, evidence, findings, and interrupted-scan reasons. Combined with rate limits, caching, and disclaimers, an agent can invoke and interpret this tool without further 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%: the schema already documents 'domain' with a pattern, length bounds, and the 'bare domain only, no https://' rule. The description repeats the bare-domain example ('yourstore.com') without adding format or edge-case detail beyond it, so the schema is doing the load-bearing 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: a scan-only quick read of whether AI agents can discover and buy from a website. The 'automated scan, not human-verified' qualifier and the explicit scope ('scan-only') distinguish it from human-verified certification or audit tools a caller might assume. Nothing in the sibling list (get_status, list_protocols, etc.) overlaps.

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?

Signals a 'quick read' and notes it is free on testnet, implying a lighter-weight alternative to a full audit, but never names a sibling or states when NOT to use it. The pointer to the readiness page for open questions is useful context but not a routing rule. Adequate, with clear gaps.

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 read-only/idempotent/non-destructive, but the description goes further: it names the exact return contents (headline, status, last verified date, ONE source URL), states the missing-name fallback, and guarantees 'never a guessed answer'. The 'Free on testnet' note discloses cost/deployment context.

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

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

Three tight sentences with no filler; the cost note and scope lead, then return shape, then the error path. Nothing is padded, though the lead sentence is fragmentary.

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-param read tool with full schema coverage and no output schema, the description is nearly self-sufficient: it conveys return fields, error semantics, and cost. Only the relationship to get_status_detail is missing.

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

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

Schema description coverage is 100% and the schema already documents the protocol parameter with examples and the list_protocols hint. The description largely restates that same guidance, adding no format or syntax detail beyond the schema.

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

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

States a specific verb and resource: status of one Ledger row (protocol/platform/wallet/stablecoin), and enumerates the returned fields. It differentiates against list_protocols explicitly, but does not distinguish itself from its closest sibling get_status_detail, which an agent also needs to disambiguate.

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?

Tells the agent how to obtain valid input ('Call list_protocols to see every name') and describes the not-found path (result="unknown" plus did_you_mean). It stops short of saying when to prefer this over get_status_detail.

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), so the bar is lower; the description still adds real behavior: free on testnet with no payment or wallet, unknown names return result="unknown" plus up to 3 did_you_mean suggestions, and empty detail fields are omitted rather than returned blank.

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 free/testnet constraint, then the payload contents in one dense but scannable clause. The field enumeration is justified because no output schema exists, though the long parenthetical chain is slightly run-on.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: headline, authoritative status, derived maturity, steward, details, dates and up to 3 sources, plus the unknown-name response shape. An agent has everything needed to call it and interpret results.

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, but the description adds meaning beyond the schema: that 'protocol' accepts names covering protocols, platforms, wallets and stablecoins alike, and that list_protocols is the authoritative name source. It reinforces rather than merely restates the parameter docs.

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 gives a specific verb+resource (a 'fuller answer for ONE Ledger row') and enumerates exactly which entities qualify (protocol, platform, wallet, stablecoin) plus the returned fields. The word 'fuller' implicitly positions it against the sibling get_status, so an agent can distinguish them 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 states the exact context (retrieve detail for one named Ledger row), documents the failure path for unknown names, and routes discovery to a named sibling ('Call list_protocols to see every name'). It does not explicitly state when to prefer get_status over this tool, so the alternative is only implied by 'fuller answer'.

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/non-destructive/non-open-world, so the safety profile is covered. The description adds genuinely new behavioral context: it returns all rows unfiltered, it is free on testnet, and it deliberately returns only name/aliases/status rather than full detail.

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 cost note and return-shape, closing with the routing pointer. No filler and nothing that restates the tool name.

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

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

With no output schema, the description carries the return-value burden and does so by naming the three returned fields and signaling the result set is complete ("Every row"). Ordering and response shape/format remain unspecified, a minor gap for a zero-param list 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?

The tool takes zero parameters, which is the baseline 4 case. The schema has 100% description coverage and there is nothing for the description to clarify about inputs; "Every row" does confirm the absence of filter arguments.

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 resource (every row in the human-verified Ledger) and enumerates exactly what it returns: name, aliases and status. It is distinguishable from get_status/get_status_detail by being the unfiltered catalog rather than a per-entity lookup.

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

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

"Use a name from here with get_status or get_status_detail" explicitly states the downstream workflow and which siblings consume its output. It lacks an explicit when-not clause (e.g., don't call this to check a single entity), so it stops short of 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 read-only, idempotent, closed-world behavior, and the description adds context annotations cannot: it is free on testnet, capped at 5 hits, returns relevance scores and matched-field labels, and refuses to guess on no match. The worked example further reveals the exact response 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?

Front-loaded with cost and purpose, and nearly every sentence carries new information (caveat, routing, no-match, example). It is a single dense paragraph, slightly overstuffed with a full JSON example, but no sentence is wasted.

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, yet the description fully covers the return shape, the field meanings (score, matched), and the failure mode. An agent has everything needed to call it and to know what to do with 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 both parameters are already documented including the 1-5 limit range. The description adds value beyond the schema by framing 'query' as a plain-English question and showing a concrete request/response pair with limit=3, though it doesn't mention the 200-char or pattern constraints the schema enforces.

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 the verb and resource precisely: free-text keyword search over a human-verified Ledger of protocols, platforms, wallets and stablecoins. It also bounds the output (up to 5 matching row NAMES), which distinguishes it from siblings like get_status_detail that return actual answers.

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 says 'It returns names, not answers: call get_status or get_status_detail with a returned name' — naming the alternatives and the condition that selects them. Also states the no-match behavior (result="none", never a guess), removing any ambiguity about fallback guessing.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context beyond that: no cost on testnet ('Free on testnet'), a hard result cap of 5 items, and a 30-day lookback window — all relevant behavioral 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?

One compact sentence with the cost/model note front-loaded and the payload shape appended as a colon list; nothing is padded. The telegraphic fragment style costs a little readability but wastes no space.

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

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

For a single-parameter read tool with no output schema, the description carries the return shape (headline, status, date, one source), the result cap, and the time window. What is missing is only the relationship to sibling status tools, which is a minor gap at this complexity.

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 only parameter's format is fully documented there, so the baseline is 3. The description's '(last 30 days)' hints that the range is bounded, but it does not clarify what happens if since_date falls outside that window or how the date is interpreted.

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 resource function — 'Recent verified Ledger changes since a date' — and enumerates the returned fields (headline, status, date, one source), so an agent knows this is a changelog/feed query rather than a status lookup like get_status. It does not explicitly name which sibling to prefer, keeping it 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?

Constraints are given ('last 30 days, max 5 items') but there is no when-to-use guidance, no mention of the siblings get_status or get_status_detail, and no criterion for choosing this over them. The agent must infer the use case from the name alone.

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