RetryHub

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

Beyond the readOnly/idempotent/closed-world annotations, the description discloses the shape of the return (tailored checklist, a 'never paste' list, and an application link) and the abstraction level ('describes documents by type only'). It also adds a security boundary — do not send card numbers, government IDs, or bank details — which annotations alone would not convey.

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 trigger condition is front-loaded, and the sentences move efficiently from purpose to inputs to outputs to exclusions to safety. The enumeration of input fields and enum values duplicates the schema slightly, which is minor waste but not a structural problem.

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 and rich annotations, the description only needs to cover selection guidance and boundaries, and it does both. Nothing an agent needs in order to choose and call 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 description coverage is 100%, so the schema already documents all three inputs and the enum. The description restates the same inputs and enumerates the processing-history values, adding no new semantic detail such as formatting, casing, or how values change the output. Baseline 3 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 states a specific verb and resource (build a document checklist) and pins the scope to 'what documents to prepare before applying for a high-risk merchant account,' which cleanly separates it from siblings like build_shutdown_checklist, check_policy_readiness, or start_application.

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 trigger ('Use when a merchant asks what documents to prepare...') plus clear exclusions ('Does not collect or review documents, approve an account, or quote fees'), which bounds the tool well. It does not name an alternative tool to route to when the request falls outside that scope, 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 establish readOnly/idempotent/non-destructive, so the description's added value is the boundary-setting: not legal advice, does not predict fund release timing, and a PII prohibition. Those are real behavioral constraints an agent would otherwise have to guess at, and nothing contradicts openWorldHint=false.

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 usage trigger, then the return contents, then the disclaimers — a sensible order with no filler. The PII warning is stated twice (description and notes schema), a minor redundancy, and the single long first sentence packs several clauses together.

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 format needn't be detailed, yet the description still summarizes checklist contents so the agent knows what the merchant will receive. Combined with the safety disclaimers and PII rules, nothing material is missing for a four-parameter, read-only 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 coverage is 100% with two documented enums, so the schema already carries parameter meaning. The description adds only a privacy caveat ('do not send card numbers, government IDs, or bank details') that reinforces the notes constraint rather than explaining any parameter's effect on the output.

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 pairs a concrete verb+resource ('returns a practical checklist') with a precisely scoped trigger domain (post-shutdown, limitation, account review, fund hold at Stripe/PayPal/Shopify Payments). That scope implicitly separates it from build_application_checklist, though no sibling is named 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?

The opening 'Use when a merchant asks what to do after a ... shutdown, limitation, account review, or fund hold' gives a clear activating condition, and the RetryHub step is gated with 'when the situation is in scope.' No explicit when-not guidance or named alternative sibling (e.g. build_application_checklist for pre-application questions) is given.

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 read-only, idempotent, closed-world, non-destructive behavior, and the description adds substantive context on top: what the ratio is compared against, that thresholds are sourced with links, that operational fixes are suggested, and two explicit disclaimers (no network-identification determination, not legal or financial advice). The credential-handling warning is a genuinely useful safety note that annotations do not cover.

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 trigger condition is front-loaded in the first clause, and every subsequent sentence carries distinct information: computation, comparison framing, threshold sourcing, fixes, and scope limits. It runs as one dense multi-clause sentence at the start, which slightly hurts scanability, but there is 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 an output schema present, the description need not explain return values, and it covers everything else an agent needs: invocation trigger, accepted input forms, analytical scope relative to Visa VAMP and Mastercard ECM, and explicit out-of-scope disclaimers. No prerequisite knowledge is 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning by framing the inputs as two alternative forms — either separate counts or a pasted free-text summary that may already be a percentage. That clarifies the relationship between the `summary` field and the numeric pair, which the schema lists only as an optional string.

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 definition names a concrete verb and resource — computes disputes divided by transactions — and enumerates the deliverables (VAMP/ECM comparison, threshold summary with source links, suggested operational fixes). Nothing in the sibling set (application checklists, policy readiness, processor fit) overlaps, so the agent can route confidently 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?

The trigger is explicit: use when the merchant supplies a monthly transaction count and dispute count, or pastes a short summary of those figures. It also states a clear negative boundary — it does not determine whether a card network has identified the business — plus a data-handling exclusion about card numbers and credentials. No named alternative sibling is offered, which keeps it just below a 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?

Beyond the read-only, idempotent annotations, the description discloses that results are keyword-based rather than legal, that the tool does not approve accounts, and that pasted text is neither stored nor echoed back. The PII exclusion adds an actionable handling constraint that 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?

It is front-loaded with the trigger, then inputs, then outputs, then caveats and data-handling rules. Every sentence adds distinct information, and the ordering follows the decision an agent actually makes.

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, the description only needs to characterize results, which it does by naming the found/missing gap categories and the suggested-fix payload. Combined with the caveats and data-handling note, an agent has everything needed to call this correctly for a five-parameter 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 coverage is 100%, so the baseline is 3, but the description goes further by framing subscriptions, delivery model, and statement descriptor as optional inputs tied to specific checks (renewal terms, delivery timing, descriptor). This tells the agent why each optional field matters, not just that it 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?

The description opens with a concrete verb and resource: it checks pasted refund, cancellation, shipping, or terms text for merchant-account review readiness. This is clearly distinguishable from sibling tools like build_application_checklist or check_dispute_ratio, which build artifacts or audit different signals.

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 trigger is explicit: use when a merchant pastes policy text and asks whether it is ready for review. It also states boundaries — a keyword check, not a legal review, and not an approval — plus a 'do not include' exclusion for customer names, order details, and financial data. It does not name a sibling alternative, which keeps it shy of a 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 declare readOnly/idempotent/non-destructive/closed-world, yet the description adds real behavioral context on top: the dimensions returned (onboarding, category tolerance, account stability, reserves, paperwork, pricing approach, disputes), the qualitative (non-numeric) nature of the output, an explicit "not financial advice" disclaimer, and a data-handling constraint against sending card numbers, government IDs, or bank 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?

Front-loaded with the trigger condition, then output nature, then limits and safety — a sensible ordering. It is a fairly dense paragraph, but each clause (what it returns, what it omits, what not to send) carries distinct information rather than 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?

For a three-required-param, closed-world advisory tool with an output schema, the description covers everything an agent needs: when to invoke, what the comparison covers, what it deliberately will not provide, and the PII restriction. The explicit disclaimer about missing fee numbers and approval odds is exactly the gap an agent would otherwise misrepresent to a merchant.

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 enum values for current_processor and situation are self-documenting, so the schema carries the parameter burden. The description only restates the three inputs generically ("the current processor, the niche, and the current situation") without adding format or edge-case meaning, so 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 (compare processor fit) and defines the exact comparison: staying with a named current processor such as Stripe/PayPal/Shopify Payments/Square versus moving to a high-risk merchant account. That framing is clearly distinct from siblings like match_merchant_account or check_policy_readiness, which imply a single-answer or single-dimension output rather than a side-by-side.

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 when a merchant asks whether to stay with their current processor ... or move to a high-risk merchant account" is an explicit trigger condition, and the description bounds scope by ruling out fee numbers, approval odds, and financial advice. It stops short of naming a sibling tool as the alternative for those excluded needs, so routing for adjacent intents is left to inference.

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?

Even though annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, the description adds substantial behavioral detail: the qualitative output tiers, the fact that a link is only returned for in-scope categories, and firm commitments about what the tool will not do (approve, quote fees, promise timelines). The PII prohibition is exactly the kind of operational constraint annotations cannot convey.

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 trigger condition is front-loaded, followed by inputs, outputs, limits, and the PII warning in a logical order. It is dense but nearly every clause carries weight; the one redundancy is restating the input list that the schema already defines.

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 advisory tool with five parameters and an output schema, the description covers the trigger, the evidence needed, the shape of the answer, the scope boundary, and the privacy constraint. An agent has everything required to decide to call it and how to frame the result to a merchant.

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 per-parameter semantics are already fully documented in the schema. The description does enumerate the same five inputs, which confirms they are the intended evidence set, but adds no format, granularity, or example guidance beyond what the schema fields already state. Baseline 3 applies when the schema carries the detail.

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 names a specific verb and resource: assessing whether a high-risk merchant account review fits a merchant's business. The stated inputs (niche, volume, country, processor, what happened) and outputs (qualitative fit, typical documents, timeline, application link) make the function unambiguous. It never names a sibling for contrast, so differentiation from tools like compare_processor_fit or build_application_checklist is left implicit.

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 opening clause gives a clear trigger: use it when a merchant asks whether a high-risk account review may fit. It also states three explicit exclusions (no approval, no fee quotes, no promised timeline) and a data-handling rule against card numbers, government IDs, and bank details. It stops short of routing the agent to a specific alternative when the answer is out of scope.

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 mark this as a non-read-only, open-world, non-idempotent write; the description adds substantial context beyond them: server-side validation of consent flags, a strict PII exclusion list, and a fallback payload when sending is unavailable. It does not warn about duplicate submissions despite idempotentHint=false, which keeps it short of perfect.

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 critical constraint (only tool that sends data) is front-loaded and the numbered checklist is scannable. The sentence is dense and long, but every clause carries an actionable requirement; nothing is redundant 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 9-parameter write tool with an output schema, the definition covers the full burden: prerequisite consent flow, allowed field set, PII prohibitions, failure behavior, and the fallback result. Nothing an agent needs to call it 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 real operating meaning: consent and user_confirmed may only be set after an explicit in-chat yes, and only the enumerated data points may be collected. The exclusion rules for SSNs, bank details, and ID documents clarify what must never flow into the free-text fields.

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 ("send the merchant's application request to the RetryHub team") and immediately scopes it with "This is the only tool that sends data," which separates it from the read-only sibling checklists and comparisons. An agent can identify the tool's role 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?

Gives an explicit ordered prerequisite workflow (ask, collect, show, confirm) plus the consequence for skipping it (server rejection), and names an alternative path when sending is unavailable. There is little left to infer about when and how to invoke this tool.

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?

Goes well beyond the readOnly/idempotent annotations by disclosing that nothing is stored, that answers are not embedded in the links, and what is returned (short summary plus both links). The PII prohibition is an explicit behavioral guardrail not derivable from any structured field.

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 trigger, then inputs, outputs, exclusions, and the safety rule — every sentence carries information. It is a dense single block, though, and the input list plus PII rule could be tightened or split for faster scanning.

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 handoff generator with full schema coverage and its own output schema, the description covers trigger, allowed inputs, return shape, downstream use (paste into application or Telegram bot), explicit non-goals, and a data-safety rule. Nothing an agent needs to call it 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; the description adds real meaning by enumerating the five non-sensitive inputs and, more importantly, stating what must never be passed (names, emails, card numbers, government IDs, bank details). It does not add format or mapping hints for the enum bands beyond the schema text.

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?

Specific verb and resource ('start... handoff', carries chat answers into an application) plus explicit scope boundaries: 'Does not submit an application, approve an account, or quote fees.' That negative framing separates it from start_application and the checklist siblings without needing to name them.

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 trigger condition is explicit: 'Use when a merchant is ready to apply with RetryHub and wants to carry what they already said in this chat into the application.' Exclusions (no submission, no approval, no fee quotes) further narrow usage, though no alternative sibling tool is named for when this is the wrong choice.

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