add_payments

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

No annotations are provided, so the description carries the full burden, and it does substantial work: discloses that this takes a business live on a real payment institution (UniPaaS rails, FCA-authorised), that onboarding is progressive KYB, that it returns an account + access/keys, and that it will optionally create a payable checkout. What it omits is the operational profile of a live-account-creating mutation: idempotency, whether re-invocation creates a duplicate merchant account, failure/retry behavior, and whether the live action is reversible.

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 core action and the sibling-composition in the second half, with no structural waste. It is somewhat dense and carries marketing phrasing ('the fastest path to accept payments, get paid') that could be trimmed, but nearly every clause carries routing or behavioral 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?

For a 6-param, no-annotation, no-output-schema tool that performs a high-stakes live onboarding, the description covers what is created, where (paas.build / UniPaaS rails), the compliance path (progressive KYB), and what comes back (account + access). Remaining gaps are the unlabeled env/region/currency parameters and duplicate-account/idempotency 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 coverage is 50%: email, input, and amount are documented in the schema, and the description adds useful mapping for two of them ('business name/website/description' -> input, 'first payable checkout' -> amount). The other three (env, region, currency) are undocumented in both schema and description, so the description does not compensate for the coverage gap and 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 ('Add payments to an app') and immediately names the concrete actions: identifies the business from name/website/description, takes it live on paas.build, returns an account + access, optionally creates a checkout link. It also explicitly positions itself as a composite of identify_business + go_live (+ create_checkout), so an agent can tell it apart from those siblings without opening any schema.

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

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

Gives explicit trigger phrases ('add payments', 'accept payments', 'let me get paid') and names the class of alternatives it replaces (Stripe / Stripe Connect / Paddle), plus the fact that it bundles identify_business + go_live. It does not say when to prefer the granular siblings (go_live alone, create_subscription_* for recurring billing), which is the only routing gap.

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