PayFresco Payment Planner

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

Annotations already declare read-only, idempotent, closed-world, non-destructive behavior, so the description's added value is the privacy contract: it never collects ID numbers, bank details, or contact details, and never contacts anyone. It also discloses an internal side flow (the eligibility screen runs first). It stops short of describing size/latency or what happens when facts are missing.

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 deliverable is front-loaded in the first clause, followed by the secondary output (site-only fields, apply link) and the exclusion set. It is a single dense sentence whose only weakness is comma-chaining several distinct obligations that would read faster as separate sentences.

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 required parameters and an output schema present, the description does not need to explain return values, and it covers purpose, boundaries, and privacy well. What is missing for a 13-parameter tool at 0% schema coverage is any guidance on which facts are needed or how to behave when the conversation did not surface them.

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 0% across 13 parameters, so the description carries the full burden and largely does not meet it – none of notes, billing_model, processing_history, or the currency arrays are explained or given format expectations. The one useful hint is that these values are 'facts already discussed', i.e. drawn from prior conversation, and the exclusion of ID/bank/contact details signals what is deliberately absent, but that leaves eleven parameters undocumented.

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 deliverable set: turn discussed business facts into copyable answers for PayFresco's application form, list site-only entries, and give the apply link. The negative scope ('Does not fill in, submit, or send an application') cleanly separates it from start_application, which an agent could otherwise confuse with this tool.

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 conveys the precondition clearly – use it once business facts have already been discussed – and gives explicit exclusions (no fill-in, no submission, no contact). 'Runs the same eligibility screen first' hints at overlap with check_eligibility, but no sibling is named as the alternative to pick instead, so routing at the boundary is implied rather than 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?

Annotations already declare readOnlyHint, idempotentHint, closed-world and non-destructive, so the safety profile is covered. The description goes further by disclosing the per-item outcome vocabulary (ready, missing, not answered, not applicable), that a copyable checklist comes back, and that post-application expectations (≈3-day approval, volume ramp, reserve, payouts, currencies) are included. It also explicitly guards against the most likely misreading — that readiness equals approval odds — which is real behavioral value beyond structured fields.

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 front-loaded paragraph with zero filler: the purpose comes first, then the returned states, then the expectations, then the non-capabilities. The requirement list is dense but every clause earns its place, and no sentence merely restates 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?

With annotations covering the safety profile and an output schema present, the description does not need to spell out return values, and it still sketches them enough to set expectations. For an 11-parameter diagnostic tool the remaining hole is the two enum parameters and notes, whose meaning rests entirely on terse field names. Overall an agent has what it needs to call this 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 description coverage is 0% across 11 parameters, so the description must carry the load, and it only partly does: the enumerated checklist items map to the boolean fields (registration documents, website with products and prices, refund policy, product description, volume estimate, processing statements, closure explanation). Nothing explains why business_category matters (several enum values look high-risk) or what processing_history buckets imply for the check, and the notes parameter is never mentioned.

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 self-check of the documents and site requirements a business must have ready before applying to PayFresco, and it enumerates them (registration documents, live website with products and prices, refund policy, product description, volume estimate, processing statements, closure explanation). The closing negatives — does not approve, quote fees, submit an application, or contact anyone — carve it away from check_eligibility, start_application, and application_handoff, so an agent can place it without opening a 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?

Usage context is explicit: run it before applying, and it is a readiness check rather than an approval chance, a fee quote, or a submission. The exclusions on the tail make the when-not side clear. The gap is that it never names a sibling directly, so the very close build_readiness_checklist (and application_handoff for the next step) is left for the agent to infer.

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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the four result classifications (documented, conditional, unsupported, unknown), the definition of 'unknown' as lacking publication-approved coverage, and an explicit list of actions it will not perform. Determinism and rate/limit behavior are left implicit but are largely covered by idempotentHint.

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 core comparison before the scope exclusions and the code-format guidance; no filler. Density is high but every sentence 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?

With an output schema present, return-value explanation is optional, and the description still usefully names the four result categories. The main gap is that all 8 parameters are optional, yet nothing says how the tool behaves on partial or empty input, nor how confident a verdict is when target_markets or payment_methods are omitted.

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 0% across 8 parameters, so the description must carry the load; it only adds 'Use ISO country and currency codes', which largely restates the ^[A-Z]{2}$/^[A-Z]{3}$ patterns. The order of parameter names in the first sentence adds no meaning beyond the keys themselves, and real ambiguities go unaddressed — notably that 'subscriptions' appears in both the billing_model and business_category enums, and the 'notes' field is never mentioned.

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 ('Compare') and enumerates exactly which inputs are matched against the PayFresco capability catalog, so the resource and operation are unmistakable. It does not, however, differentiate itself from the closely related sibling check_eligibility or application_readiness, which an agent would likely weigh against this tool.

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?

Clear exclusions state that it does not approve a merchant, quote a fee, submit an application, or contact anyone, which implicitly routes the agent to application_handoff/start_application for those needs. There is no positive statement of when to choose this over check_eligibility or application_readiness, so it stops short of full when/when-not 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value beyond that by disclaiming what the output does NOT signify — not legal compliance, not underwriting approval, not production readiness — which prevents the agent from over-claiming on the returned checklist. No rate limits, prerequisites, or input-sensitivity notes, but the output schema covers returns.

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 primary purpose before the caveats, and no filler. The first sentence is a dense feature list rather than flowing prose, which is acceptable for a checklist builder but slightly harder to parse than a structured scope statement.

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 values need not be explained, and the annotations carry the safety profile. However, for an 8-parameter, zero-coverage, zero-required tool, the definition leaves the agent guessing which inputs matter (billing_model? business_category?) and whether calling it with no arguments is meaningful. Adequate but with clear gaps in input guidance and sibling routing.

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 0% across 8 parameters, yet the description mentions none of them by name and gives no format, default, or interaction guidance. The pair `settlement_currencies` vs `presentment_currencies` and the `target_markets` array (which references a 2-letter country pattern, despite the prose emphasis on UK/EU/EEA distinction) are exactly where an agent needs meaning added, and nothing is provided.

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?

Uses a specific verb ("Build") plus a concrete artifact ("operational preparation checklist") and enumerates the domains it covers (policies, refunds, fulfillment, billing disclosures, currency, auth questions, reconciliation). The negative scope statements ("Does not collect documents") separate it from the application/document-handling siblings, though no sibling is named explicitly, so the agent must infer the split from `application_readiness` and `check_eligibility` on its own.

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 implied by the exclusion list: no documents collected (use the application tools for that) and no legal/underwriting/production determination. But there is no explicit "call this when..." statement and no named alternative such as `application_readiness` or `assess_payment_setup`, so routing between the eight siblings 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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, and the description adds real context beyond that: it names the rule sources (capability catalog, sanctioned-jurisdiction and app-prohibited category rules) and enumerates the five possible verdicts plus the accompanying payload. It doesn't disclose data freshness, coverage limits, or what happens when inputs are omitted (all 7 params are optional), which keeps it short of 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?

Three dense sentences, front-loaded with the purpose and ending with the negative scope, with no filler. Slight redundancy in re-explaining return values that the output schema already documents.

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 the verdict enumeration is technically duplicative, but the exclusions and rule sources are genuinely necessary context for a compliance-adjacent screening tool. The main missing piece is guidance on what happens with the zero required parameters and how the optional booleans/markets affect the verdict.

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 0% across 7 parameters, so the description must carry the load: it does map five of them (registration country, target markets, category, volume band, processing history) to the screening logic. But previous_account_closed_by_provider is never mentioned, and the format expectations for registration_country (ISO-2 uppercase) and target_markets are left entirely to the schema. Partial compensation, so a baseline-adjacent 3.

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 ("Quick qualitative screen of whether a business can apply to PayFresco") plus the exact input dimensions driving the verdict. The closing sentence enumerates what it does NOT do, which cleanly separates it from start_application, application_handoff, and assess_payment_setup.

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?

Frames the tool as a pre-application, pre-quote screen and explicitly excludes approval, approval-odds estimation, fee quoting, submission, and outreach, which implicitly routes the agent to the application/assessment siblings. It never names those siblings directly, so the agent must infer the handoff point rather than being told it.

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/closed-world, so the description earns credit for what it adds: it does not move money, it never invents or quotes a PayFresco fee or exchange rate, and its output is labeled an illustration based on the user's numbers. This is meaningful trust/safety context an agent would otherwise have to guess. It stops short of 5 by not saying how the user-supplied fee assumption flows through the illustration or what happens if it is omitted.

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 core facts are front-loaded, but the opening sentence is an overlong clause stack and repeats the filler phrase 'the user supplies' twice within one sentence. The content earns its place, but the phrasing could be tightened without losing 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?

The presence of an output schema and full read-only annotations lowers the burden considerably, and the description covers the safety and 'illustration only' framing well. It is still incomplete for a 7-parameter tool: defaults for months and currency semantics (does currency affect the computation or just labels?) are nowhere addressed.

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 0%, so the description must carry parameter meaning. It explains monthly_volume, fee_percent_assumption, and show_starting_cap (including the $3k/day ramp), and hints at example_week_start via 'an example payout week'. However, notes, months, and currency are never mentioned anywhere, leaving three of seven parameters with no meaning at all.

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: it illustrates the 10% reserve on a 90-day rolling basis plus the T+2 M/W/F payout cadence. That is enough to tell it apart from the sibling onboarding/eligibility tools, which deal with applications and readiness rather than modeling payouts. It never names a sibling explicitly, 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?

Usage is implied rather than stated: it consumes a user-supplied monthly volume and an optional fee percentage, and 'Set show_starting_cap to compare...' gives one conditional instruction. There is no explicit when-to-use/when-not-to-use guidance and no routing to plan_currency_settlement or assess_payment_setup for adjacent questions.

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, it discloses that rates and amounts are caller-supplied, no rates or fees are invented, reserve and payout timing are conditional on underwriting rather than promises, and no money moves. These are meaningful operational limits that an agent would not get from the annotations alone.

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 and mostly efficient, with each sentence adding purpose or behavior. There is minor redundancy around caller-supplied rates and not inventing rates/fees, but no major bloat.

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 description covers the tool's behavioral boundaries well and an output schema exists, so return values need not be explained. For a five-parameter planning tool with no schema descriptions, however, input guidance is thin, so the definition is only moderately complete.

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?

With 0% schema description coverage, the description must explain the five inputs. It loosely maps 'caller-supplied amounts' and 'exchange-rate assumptions' to two parameters, but it does not explain notes, the currency arrays, item constraints, or max lengths, leaving most parameter meaning to the bare 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 names a concrete action ('Build a route table') and the exact resource domain ('customer payment currencies to desired settlement currencies'), and it states the key determinations (conversion required, route documented). It does not explicitly contrast with sibling tools such as estimate_payout_schedule, so sibling differentiation is implicit rather than stated.

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 implied: this is a planning/simulation step that uses caller-supplied amounts and rates and does not move money. However, the description never says when to choose this tool over sibling planning or payout tools, nor does it list prerequisites or exclusions.

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 only declare readOnlyHint=false and openWorldHint=true; the description goes far beyond by disclosing that the server rejects requests when consent flags are false, enumerating prohibited sensitive data (SSN/tax ID, bank/routing/IBAN, card numbers, passwords, ID documents), forbidding extra fields, and describing the degraded result when sending is not available. For an external-send tool that is not idempotent, this is exactly the operational context an agent needs and cannot infer.

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 purpose, then a numbered mandatory checklist, then the fallback — logical order with no filler. It is dense and runs as one paragraph, and the field enumeration partially overlaps the schema, but every sentence carries operational weight.

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 a high-stakes external send with nine parameters and gated consent; the description covers the trigger conditions, the exact data boundary, the rejection behavior, and the fallback path, while an output schema exists so return values need not be explained. Nothing an agent must know before calling 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 baseline is 3, and the description adds real meaning on top: it defines the gate semantics for consent and user_confirmed (true only after the merchant's explicit yes in chat), enumerates the exact collectible field set including the optional Telegram handle and current processor, and constrains what_happened to shutdown/hold/other. It does not restate per-field formats (lengths, email format, monthly_volume in merchant's words), but those are already in 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 — send the merchant's application request to the PayFresco team — and immediately scopes it with 'This is the only tool that sends data,' which separates it from the read-only siblings (application_readiness, check_eligibility, assess_payment_setup). An agent knows exactly what this tool does and that no sibling substitutes for the send action.

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 four-step precondition sequence (ask about contact, collect only listed fields, show every value verbatim, get explicit yes) plus the failure condition (server rejects without consent/user_confirmed) and a named alternative path when sending is unavailable (application link and Telegram bot). This is when-to-use, how-to-qualify, and fallback routing all in one place.

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