Merchant of record: create products, payment links, checkouts, subscriptions and invoices, with VAT and sales tax handled. OAuth sign-in, no API key to paste.
Scored across 31 tools
Most tools have clearly distinct domain+action purposes, and descriptions are explicit. A few pairs can still be confused, especially agenta_subscriptions_credit vs agenta_subscriptions_credits, plus overlapping verification/audit state across agenta_status_get, agenta_verify_status, and agenta_audit_show.
The agenta_<domain>_<action> convention is strong and predictable across nearly all tools. Minor deviations exist: pay vs payments, get vs show for single-resource reads, and noun-style names like id_link, receipt, and declaration.
At 31 tools this exceeds the 25+ threshold and feels heavy for a single MCP server. Several operations (e.g., subscription credit/credits, multiple status/verification/audit summaries) could be consolidated even though the broad payment-platform scope justifies many tools.
Core workflows are covered, but there are notable gaps: no refund/cancel for checkout payments, no update/delete/get for products, no single-subscription get, and limited customer operations. These omissions would likely force workarounds for full lifecycle management.
Ask for the free Revenue & Pricing Audit. Starts a written review of their pricing and checkout; it costs nothing and does not block going live.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The page on the merchant website where they sell it | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. | |
| category | No | saas | digital | services | marketplace | physical | other | |
| delivery | No | instant_digital | scheduled_service | physical_shipped | other | |
| description | No | One sentence on what it does |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is not read-only, is open-world, and is non-destructive. The description adds useful behavioral context beyond that: the audit costs nothing and does not block going live. It does not, however, explain what happens after the request or how the written review is delivered.
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 two tightly written sentences with no wasted words. It front-loads the core action and then adds the most useful qualifying details (free, non-blocking) in the second 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 the 100% schema coverage, rich annotations, and no output schema, the description provides enough context to invoke the tool correctly: it explains what the request does, that it is free, and that it is non-blocking. It could be more complete by pointing to the sibling tool for retrieving the resulting audit, but that is a minor 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?
Schema description coverage is 100%, so the schema itself fully documents all five parameters, including enums and the required URL. The description does not add any parameter-level meaning beyond what the schema already provides, making the baseline score of 3 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-action ('Ask for') and resource ('Revenue & Pricing Audit') and explains that it starts a written review of pricing and checkout. It is clear what the tool does, but it does not distinguish itself from the sibling tool agenta_audit_show, which likely retrieves the resulting audit.
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 description implies when to use the tool by noting it is free and 'does not block going live,' but it does not explicitly say when to choose it over alternatives such as agenta_audit_show. Usage is therefore implied rather than fully guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The audit state, and download the report PDF once it exists. Returns whether an audit was requested, its state, its grade and the report PDF link once it is written. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| output | No | Save the report PDF here (default ./revenue-audit.pdf) | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. | |
| download | No | Save the report PDF once it exists (a terminal does; a tool call returns the link) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. 'Changes nothing' largely restates readOnly, and the useful addition is the timing note that the PDF link appears only once the report is written. No pagination, auth or failure behavior is discussed.
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 prose is brief, but the first fragment is malformed and the second sentence repeats the PDF-availability point already made in the first ('download the report PDF once it exists' / 'the report PDF link once it is written'). Minor redundancy and a weak lead-in keep it from being clean.
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 zero-required-parameter read tool with rich annotations and no output schema, the description does the important work of enumerating the returned fields (requested flag, state, grade, PDF link). Only the implicit prerequisite that an audit must first be requested is left for the agent to infer.
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%, with each of the three parameters (output, business, download) fully documented in the schema itself. The description adds no syntax, default or scoping detail beyond the schema, so the 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?
The description names the resource (audit state / report PDF) and enumerates exactly what is returned: whether an audit was requested, its state, grade and PDF link. The opening clause ('The audit state, and download the report PDF...') is grammatically broken, but the second sentence rescues the intent and separates this read tool from the sibling agenta_audit_request.
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: you call it to inspect the state of an audit you (or the request tool) started. The phrase 'once it exists' hints at the prerequisite that an audit must first be requested, but no alternative is named and no when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a business you manage — a client's business, or another app of your company. Adds a business this account manages, for a client or another app. Optionally invites the client as its admin by email. Returns the business id; pass it as business on other tools to act for it.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name buyers see | |
| country | Yes | Where it is registered, e.g. EE | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. | |
| clientEmail | No | Invite your client as its admin. Omit to run it yourself | |
| inviteEmail | No | Email the invitation (switch off to send the link yourself) | |
| sameCompany | No | Another app of your own company (verified and priced with you) instead of a client |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, covering safety. The description adds that it optionally invites the client as admin and returns the business id, useful beyond annotations, but doesn't detail permissions, side effects of inviting, or error conditions.
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 tight sentences with no waste; the core action and key outcome (returning the id for reuse) are front-loaded. Every clause earns 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 full schema coverage and no output schema, the description is nearly complete: it explains the add, optional invite, and the returned id for chaining. It could mention required fields or validation, but it's largely sufficient.
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 parameters are fully documented in the schema. The description reiterates that the clientEmail option invites the client and hints at business id usage but adds no extra syntax or default behavior beyond what the schema already states.
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 clear verb+resource ('Add a business you manage') and clarifies scope ('a client's business, or another app of your company'). It distinguishes itself from agenta_businesses_list/get by describing the create action, though it never names those siblings 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 implies usage by saying businesses you manage for clients or apps, but offers no explicit when-to-use vs when-not-to-use guidance or alternative tools. The mention of passing the returned id to other tools gives some context, but no decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show one business you manage. Returns one managed business by id: its name, status, whether its identity is verified and any open invitation. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The business id | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description reinforces this with 'Changes nothing.' and additionally discloses the returned content (name, status, verification state, open invitation), which goes beyond the annotations. It stops short of describing auth requirements or error behavior for an unknown id.
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 tight, front-loaded sentences with the resource and scope stated first. 'Changes nothing' is slightly redundant with the readOnly/destructive annotations but costs almost nothing.
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 enumerates the returned fields, and the annotation set covers the safety profile. Only minor gaps remain around the act-as parameter's practical implications and failure modes.
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%, including the non-obvious act-as 'business' parameter, so the schema carries the parameter burden. The description adds no syntax, format, or id-source detail beyond what the schema documents, 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 and resource ('Show one business you manage... Returns one managed business by id'), which cleanly separates it from the plural sibling agenta_businesses_list and the mutating agenta_businesses_create/invite. An agent can identify the operation 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?
Implies usage ('one business... by id') but never states when to choose this over agenta_businesses_list or what to do if the id is unknown. The act-as parameter's omit-to-act-as-yourself guidance lives in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the identity check link for your client (only they can complete it). Returns the identity check link for one managed business. Only the client can complete it, so send them the link. Changes nothing if they are already verified.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The business id | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=false declared, the description usefully clarifies the side effect: it may generate a link, but 'changes nothing if they are already verified,' which is meaningful idempotency context. It does not explain permission requirements, whether existing links are reused or rotated, or how the link is delivered.
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 purpose is front-loaded, but 'only they can complete it' is stated twice across the second and third sentences, and the return value is restated after already being introduced. Roughly a third of the text is redundant.
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 two-parameter tool with no output schema, it does cover the key return value (the link) and the client-completion constraint. It omits link lifetime/expiry, behavior when a link already exists but is unverified, and any routing advice versus the verify family, which leaves gaps for an openWorldHint 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 description coverage is 100%, so both 'id' and 'business' are already documented in the schema. The phrase 'for one managed business' loosely reinforces the 'business' parameter but adds no format, syntax, or edge-case detail beyond the structured field.
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 concrete verb and resource: fetching/creating the identity check link for one managed business. It is distinguishable from siblings like agenta_verify_submit or agenta_businesses_get. However, the title says 'Create' while the body says 'Get,' leaving the verb slightly ambiguous as to whether this mutates state.
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 implies usage by telling the agent to send the link to the client, and the 'only they can complete it' note frames who acts on it. There is no explicit guidance on when to prefer this over the agenta_verify_* tools or when it should not be called.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send your client's invitation again (a new link; the old one stops working). Sends a new invitation link to the client admin of one managed business; the previous link stops working. Sends an email unless email is false.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The business id | |
| No | Email it (switch off to send the link yourself) | ||
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and openWorldHint=true, and the description usefully adds the side effect that the previous link is invalidated and that an email goes out unless email=false. However, it never says whether the new link is returned, what the response looks like, or that this is a mutation with an external send, leaving real behavioral gaps for a non-read-only, open-world call.
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 same two facts (a new link is sent; the old one stops working) are stated three times in three sentences. It is bloated through redundancy rather than under-specification, and a meaningful detail (return value) is omitted while the repetition is kept.
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?
Covers the core action and the email toggle, but for a mutation with no output schema the description should tell the caller what comes back (notably the new link when email=false) and how this relates to the revoke-invite sibling. As written it is adequate but incomplete.
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 parameters. The description only echoes the email flag's behavior and says nothing about 'id' or the 'business' acting-on-behalf parameter, so it adds essentially no meaning beyond the schema baseline.
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 (send/invite) and resource (business invitation) and adds the distinguishing fact that a NEW link is issued and the old one stops working. It does not, however, differentiate itself from siblings like agenta_businesses_revoke_invite or agenta_businesses_id_link, so an agent still has to guess which is appropriate.
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 tool appears to be for re-sending a lapsed or lost invitation, and the 'email is false' case hints at when a caller would want the raw link instead of an email. There is no explicit when-to-use/when-not statement and no routing to the revoke_invite sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the businesses you manage. Returns the businesses this account manages (its clients or its other apps), with id, name and status. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and "Changes nothing" merely restates that. It does add useful behavioral context absent from annotations: the return payload includes id, name and status, which matters because there is no output schema. No mention of pagination, ordering, or auth requirements.
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, purpose first, then return shape, then safety. No filler and nothing redundant enough to trim.
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 parameterless read-only list tool with no output schema, the description covers purpose, scope and returned fields, and annotations cover the safety profile. The only gap is any guidance on result size/pagination or how to choose this over the single-business sibling.
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 single 'business' parameter ("Act for this business you manage (its id). Omit to act as yourself.") is fully documented by the schema itself. The description adds no extra meaning about the parameter, so the 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?
Specific verb+resource ("List the businesses you manage") with an added scope clarification that the result covers clients or other apps. It is clearly distinguishable in spirit from agenta_businesses_get, but the description never names a sibling or explicitly contrasts with one, 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?
The description states what the tool returns but gives no when-to-use guidance, no condition for choosing it over agenta_businesses_get or agenta_customers_list, and no prerequisites. Usage is only inferable from the verb 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Withdraw your client's open invitation. Withdraws the open invitation of one managed business so its link stops working.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The business id | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the destructive nature is covered. The description adds the consequence that the invitation link stops working, which is useful beyond the annotations. However, it does not discuss reversibility, permissions, or side effects.
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 two short sentences and front-loads the action. The second sentence somewhat repeats the first but adds the scope and consequence, so it mostly earns its place. There is minor redundancy but no 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?
For a simple mutation tool with full schema coverage and clear annotations, the description provides adequate purpose and effect. Missing details like prerequisites or behavior when the invite is already revoked are minor for this tool's 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 description coverage is 100%, with both parameters documented directly in the schema. The description adds no additional syntax, format, or meaning for the 'id' or 'business' parameters. Baseline 3 is appropriate when the schema fully carries parameter semantics.
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 (withdraw/revoke), resource (open invitation), and scope (one managed business). It clearly distinguishes the action from invite creation, though it does not explicitly name the sibling invite tool. The outcome 'link stops working' adds useful specificity.
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 description gives no explicit when-to-use guidance or alternatives. It does not say when this tool should be chosen over related tools like agenta_businesses_invite or agenta_businesses_id_link. Usage is only implied by the action name and title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List customers. Returns the people who bought from the merchant, with their email, name, country and customer id, up to limit (1 to 100). Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page (default 10) | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered; 'Changes nothing' merely restates destructiveHint=false. The description adds useful scope ('people who bought from the merchant') but says nothing about per-business authorization needs or that results are scoped to one page.
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, front-loaded sentences with no filler; the primary purpose leads. The parenthetical limit range duplicates the schema and the closing 'Changes nothing' is redundant with the annotations, so it is not perfectly lean.
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 enumerates the returned fields (email, name, country, customer id), which is the key missing structured information. For a two-optional-parameter read tool this is nearly sufficient, though pagination behavior (no cursor/offset parameter exists) and acting-identity effects are unaddressed.
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 both parameters are already documented in the schema. The description repeats the limit range (1 to 100) without adding new meaning and never mentions the 'business' parameter that switches the acting identity.
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 ('List customers') and clarifies the scope as 'the people who bought from the merchant', which is distinct from sibling list tools such as agenta_products_list or agenta_invoices_list. It does not explicitly name a sibling to contrast with, but the resource is unambiguous.
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 tool versus alternatives (e.g. looking up a single customer or listing invoices), nor any stated prerequisites such as required authorization for the business being queried. Usage is only implied by the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a discount code working. Stops one discount code working for new purchases; subscribers who already used it keep their discount.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The discount code id | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious semantics: existing subscribers retain their discount, which prevents an agent from assuming a blanket revocation. It stops short of stating reversibility or permission requirements.
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?
Short and front-loaded, but the second sentence largely restates the first ('Stop a discount code working' / 'Stops one discount code working for new purchases') before adding the one new fact. That duplication costs a point against strict 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 simple two-parameter mutation with no output schema and annotations covering destructiveness, the description supplies the key behavioral nuance an agent needs. Missing only reversibility/auth details, which is a minor gap at this complexity level.
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% with only two parameters, so the schema already documents 'id' and 'business' fully. The description mentions 'one discount code' (implying a single id) but adds no format or scoping detail beyond the schema. 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 and resource ('Stop a discount code working') and clarifies what 'archive' actually means operationally. It is distinguishable from sibling read tools like discounts_show and create tools, though it never names an alternative for reversing the 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?
Usage is implied by the effect ('for new purchases') rather than stated as guidance. It never says when to use archive versus leaving a code alone, nor whether it can be undone, and no sibling alternative is offered. Minimum viable routing information only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a discount code buyers type at checkout. Creates a code buyers type at checkout to get money off, or a tracking-only code that records who a referral brought in. Returns the code and its id.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The code buyers type at checkout | |
| name | No | Your label for it, shown on the buyer’s invoice | |
| plan | No | Limit it to one plan: the product id. Omit for all plans | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. | |
| amountOff | No | Fixed amount off the first invoice, e.g. 5.00 | |
| expiresAt | No | Date the code stops working (YYYY-MM-DD) | |
| percentOff | No | Percentage off the first invoice, e.g. 20 | |
| maxRedemptions | No | Stop the code working after this many subscribers use it |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the write-but-not-destructive profile is covered. The description adds useful context: it discloses the two behavioral modes (money-off vs tracking-only) and the return value ("the code and its id"). It omits auth requirements, duplicate-code handling, and idempotency, so it adds moderate value beyond annotations.
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 main purpose is front-loaded, but the first two clauses are near-verbatim repeats ("buyers type at checkout" appears twice), wasting a sentence. The tool would read better with the redundancy removed.
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 8 parameters at 100% schema coverage, no output schema, and simple flat parameters, the description is nearly complete. Explaining the return value (code and id) compensates for the missing output schema, though it could say more about behavior on invalid or duplicate codes.
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 every parameter is already documented in the schema and the baseline is 3. The description adds no parameter-level detail (no mention of code format, plan scoping, or business acting-on-behalf) beyond what the schema provides.
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 discount code") and distinguishes two functional variants: a money-off code versus a tracking-only referral code. It does not explicitly name or contrast with siblings like agenta_discounts_show or agenta_discounts_archive, but the create intent is unambiguous.
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 description implies usage by describing the two code types an agent might want, but it never states when to choose this tool over alternatives such as discounts_list or discounts_show. No exclusions or prerequisites are given, leaving usage to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List discount codes. Returns the merchant's discount codes with their id, whether each is a discount or tracking only, the plan it applies to and whether it is active, up to limit (1 to 100). Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page (default 10) | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and 'Changes nothing' largely restates that. The description does add real value by disclosing the shape of the returned records (id, discount vs tracking, applicable plan, active flag), but omits pagination behavior beyond the limit wording.
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 the core action front-loaded and no filler. The return-field sentence earns its place since there is no output schema.
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 covers the returned fields, and annotations carry the safety profile. It is nearly complete, only slightly thin on pagination and the business-scoping parameter.
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 both parameters. The description restates the limit range ('up to limit (1 to 100)') but says nothing about the business parameter or its purpose of acting on behalf of a managed business, adding little 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+resource ('List discount codes') and even enumerates the returned fields (id, discount/tracking, plan, active). This clearly separates it from write siblings like discounts_create and discounts_archive, though it never names discounts_show to distinguish listing from fetching a single code.
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 by the verb 'List' — an agent can infer it retrieves the collection rather than one code, but there is no explicit when-to-use or when-not-to-use guidance and no pointer to alternatives such as agenta_discounts_show.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show one discount code: what it takes off and how many people used it. Returns one discount code by id: what it takes off, its limits, and how many buyers used it. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The discount code id | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true; the description's 'Changes nothing' corroborates but does not extend that. It adds useful return-content context (limits, buyer count) but says nothing about permissions, the business-scoping behavior, 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?
Front-loaded and short, but the first and second sentences substantially repeat the same idea ('what it takes off... how many used it' restated as 'what it takes off, its limits, and how many buyers used it'), which is redundant rather than additive.
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 does cover the return payload, and the read-only nature is covered by annotations. It is nearly complete for a simple lookup, with the only gap being the business/act-as parameter's 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%, so both parameters are already documented in the schema. The description only confirms 'by id' and never mentions the business parameter's act-on-behalf semantics, so it adds little beyond the schema baseline.
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 resource (one discount code by id) and characterizes what is returned: discount amount, limits, and usage count. The singular 'one... by id' cleanly distinguishes it from the sibling list/create/archive discount tools.
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 'by id' – an agent can infer this is the single-record lookup versus agenta_discounts_list. However, no explicit when-to-use/when-not guidance or named alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List invoices. Returns the merchant's invoices with their id, amount, currency, status and buyer, up to limit (1 to 100). Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page (default 10) | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so 'Changes nothing' is largely redundant with the structured data. The description does add the returned field set and the limit range, which is modest extra context beyond the annotations but not rich behavioral disclosure.
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?
Short, front-loaded, and front-loads the verb+resource. 'Changes nothing' is mildly redundant given the readOnlyHint annotation, keeping it just below a 5.
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 correctly compensates by enumerating the returned fields (id, amount, currency, status, buyer) and the limit bound. For a simple, zero-required-param list tool this is nearly complete, missing only pagination 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%, so both parameters are already documented in the schema. The description restates the limit range (1 to 100) already in the schema and says nothing about the 'business' parameter, so it adds no meaning beyond the schema. Baseline 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?
Statement of a specific verb (List) and resource (invoices), plus the returned fields (id, amount, currency, status, buyer). However, it does not distinguish itself from the two sibling invoice tools (agenta_invoices_receipt, agenta_invoices_send_receipt) or explain the distinctions, so it stops 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 by the name and by 'Returns the merchant's invoices' but there is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives. For a listing tool that is largely self-evident, a 3 is fair.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download the receipt PDF for a paid invoice. Returns the receipt PDF for one paid invoice; a tool call gets the link, the CLI saves the file. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The invoice id | |
| output | No | File path to save the PDF to | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/not-destructive, so "Changes nothing" is largely redundant. The genuinely additive detail is "a tool call gets the link, the CLI saves the file", which explains that the tool must be paired with client-side writing - behavior not visible in the annotations.
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 compact sentences, front-loaded with the action and scope. Slight redundancy in "Changes nothing" against the readOnlyHint annotation, but nothing wasted overall.
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 explains the return path (link retrieved, PDF saved by CLI). For a simple three-param read tool with full annotation coverage, that is close to complete; permission/authorization context is only implied.
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 all three parameters (id, output, business) are already documented in the schema. The description adds a marginal hint that the file is saved by the CLI, aligning with the `output` path parameter, but no extra semantics beyond that.
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 (Download) plus resource (receipt PDF) and a precondition (paid invoice). It is clearly distinguishable from the sibling agenta_invoices_send_receipt, which sends rather than downloads.
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?
"For a paid invoice" implies the eligible state for use, but no when-not conditions or alternatives (e.g. send_receipt, list) are named. Usage is implied rather than explicitly routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-send the receipt email to the buyer on file. Emails the receipt for one paid invoice again to the buyer's address on file. Sends an email to the buyer.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The invoice id | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the external-send nature is covered structurally. The description adds two useful constraints beyond the annotations: the invoice must be paid, and the address is the buyer's on-file address (not caller-supplied). It says nothing about repeat-send limits, failure modes, or whether a resend is idempotent.
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 say essentially the same thing three times ('Re-send the receipt email to the buyer on file' / 'Emails the receipt ... again to the buyer's address on file' / 'Sends an email to the buyer'). The opening sentence is well front-loaded, but two of three sentences are pure restatement and fail to earn their 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 simple two-parameter tool with full schema coverage and no output schema, the description covers the core action adequately. It omits what an agent would want to know before calling: whether resending repeatedly is allowed, what happens if the invoice is unpaid, and any confirmation of effect.
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 both parameters (id, business) are already documented in the schema, and the description adds no syntax, format, or semantics beyond that. Baseline 3 applies when the schema carries the parameter burden.
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 (re-send the receipt email) and clarifies the recipient is the buyer on file, so the action is unambiguous. It does not distinguish itself from the sibling agenta_invoices_receipt, which an agent may confuse with this one.
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?
No when-to-use guidance, no preconditions, and no mention of the closely named sibling agenta_invoices_receipt as an alternative. The only signal is the name itself, which the agent must infer from.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a checkout session. Creates a one-off checkout for an amount and returns its checkoutUrl to send to the buyer, its sessionId and when it expires. The buyer pays by card; tax is added by AgentaOS.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Pre-populate buyer email | ||
| amount | Yes | Payment amount (e.g. 50.00) | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. | |
| currency | No | Currency code (e.g. EUR, USD) | |
| description | No | Description shown on checkout page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and openWorldHint=true, so the mutating/external nature is covered. The description adds genuinely useful behavior: the returned checkoutUrl/sessionId/expiry, that the buyer pays by card, and that tax is added by AgentaOS rather than supplied by the caller. It omits auth/permission needs for the business parameter, keeping it below 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?
Two tight sentences, front-loaded with the core action and then the return values. No filler or repetition of 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 no output schema, the description correctly compensates by naming the return fields (checkoutUrl, sessionId, expiry). Annotations plus schema cover most remaining ground; only permission/auth nuances for acting as a business are 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. The description contributes only marginal extra meaning, notably that amount is pre-tax and that the currency/business context belongs to AgentaOS — useful but not beyond what a well-documented schema already conveys.
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 ('Create a checkout session') and adds scope ('one-off checkout for an amount') plus the returned artifacts. It is clearly distinct from the read-only siblings agenta_pay_get/agenta_pay_list, though it does not explicitly contrast itself with other creation tools like subscriptions_create or invoices.
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 description implies usage ('returns its checkoutUrl to send to the buyer') but never states when to choose this over agenta_subscriptions_create or invoice flows, nor any prerequisites or exclusions. Usage is inferred rather than guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get checkout session status. Returns one checkout by sessionId: open, completed (paid), expired or cancelled, with amount, currency and link. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| business | No | Act for this business you manage (its id). Omit to act as yourself. | |
| sessionId | Yes | The checkout session id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description still adds real value by enumerating the possible statuses (open, completed/paid, expired, cancelled) and the returned fields, which matters because there is no output schema.
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 action and immediately followed by the return contract. 'Changes nothing' is slightly redundant against readOnlyHint but otherwise there is no waste.
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 two-parameter read tool with no output schema, the description supplies exactly what is missing: the return shape, the status values, and the fields returned. An agent has everything needed to call and interpret it.
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 both parameters are already documented in the schema. The description mentions sessionId but adds no format or syntax detail beyond it, making the baseline 3 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?
States a specific verb and resource ('Get checkout session status') and pins down the exact return: one checkout by sessionId. It is clearly distinguishable from the sibling list (agenta_pay_list) and create (agenta_pay_checkout) tools.
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?
'Returns one checkout by sessionId' implies a singular lookup, which is enough to infer usage versus the list tool, but no explicit when-to-use, prerequisites, or named alternatives are given. Usage 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.
List checkout sessions. Returns checkouts with their status, amount and sessionId, optionally only one status (open, completed, expired, cancelled), up to limit (1 to 100). Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page (default 10) | |
| status | No | Filter: open, completed, expired, cancelled | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, and 'Changes nothing' reinforces the read-only contract. The description adds genuinely useful behavioral context by disclosing the returned fields (status, amount, sessionId) and the limit cap of 1 to 100, though it says nothing about pagination/page-walking or auth requirements.
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 purpose front-loaded, followed by return content, filtering, and a closing safety note. No wasted words, though the enumerated return fields and filter options slightly overlap with the schema.
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 explains return contents, and it covers the filtering and size options for a zero-required-param list tool. The main gap is pagination behavior (whether other pages exist beyond the limit), which is not addressed anywhere.
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 all three parameters (limit, status enum, business) are already documented in the schema. The description echoes the status enum values and limit range but adds no new syntax or semantics, so it sits at the baseline 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?
The description opens with a specific verb+resource ('List checkout sessions') and states the returned fields (status, amount, sessionId), so an agent can tell it apart from agenta_pay_get and agenta_pay_checkout by intent. It stops short of naming those siblings or explicitly contrasting single vs list retrieval, keeping it below 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?
It notes the optional single-status filter and the limit range but never states when to use this tool versus agenta_pay_get or agenta_pay_checkout, and gives no exclusions or preconditions. Usage is only implied by the verb 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a product (one-time) or a subscription plan. Creates something buyers can pay for: a one-time product, or a subscription plan with an interval. Returns the product id and its buyer link, which can be shared as is.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Product name buyers see | |
| amount | Yes | Price (e.g. 49.00) | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. | |
| currency | No | Currency code (e.g. EUR, USD) | |
| interval | No | Billing cadence for a plan: month or year | |
| cancelUrl | No | https URL buyers return to if they back out | |
| trialDays | No | Trial length for a plan, in days | |
| successUrl | No | https URL buyers return to after paying (we append ?sessionId=…) | |
| description | No | Description shown on the checkout page | |
| trialAmount | No | Price of the whole trial (e.g. 9.00). Leave it out and the trial is free | |
| subscription | No | Recurring plan instead of a one-time product |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the returned artifact (product id plus a shareable buyer link), which matters because there is no output schema. It still says nothing about required permissions or whether repeating a call creates duplicates.
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 sentences with the core purpose front-loaded and no filler. The second sentence partially restates the first ('something buyers can pay for' re-explains the one-time/subscription split), which is minor redundancy rather than waste.
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 11-parameter creation tool with full schema coverage and annotations, the description covers the two creation modes and the return payload, which compensates for the missing output schema. It does not touch the business/currency/trial nuances, but the schema carries those adequately.
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 every one of the 11 parameters is already documented in the schema. The description echoes the interval/plan relationship but adds no format, default, or interaction detail beyond what the schema states, so the baseline of 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?
The first sentence names a specific verb and resource and immediately splits it into the two supported modes: one-time product vs subscription plan. This scope is unambiguous and clearly distinct from the read-only sibling agenta_products_list.
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 mention of 'a subscription plan with an interval' hints that recurring billing requires the interval parameter, but there is no explicit when-to-use statement, no exclusions, and no named alternative. The agent must infer the choice from the schema rather than the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products and plans. Returns the merchant's products and subscription plans with their ids, prices, currencies and buyer links, up to limit (1 to 100). Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page (default 10) | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered by structured data; 'Changes nothing' largely restates that. The description adds the 1–100 limit cap, which is mild extra context, but says nothing about pagination behavior, result ordering, or whether more results exist beyond the limit.
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 tightly written sentences with no filler, and the highest-value information (what is returned) plus the safety signal are front-loaded. Nothing is repeated or padded.
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?
There is no output schema, so the description correctly takes on the job of describing the return payload (ids, prices, currencies, buyer links), and annotations carry the safety profile. The only gap is pagination advice — with a bare 'limit' and no cursor/offset parameter, the agent isn't told whether results are truncated or how to fetch beyond the limit.
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 both parameters (limit, business) are already documented in the schema, making the 3 baseline correct. The description echoes the limit range but adds no meaning beyond it, and never mentions the 'business' parameter that lets the caller act on behalf of a managed business.
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 ('List products and plans') and even enumerates the returned fields (ids, prices, currencies, buyer links), so the agent knows exactly what this returns. It does not, however, differentiate itself from adjacent list tools such as agenta_subscriptions_list or agenta_products_create, leaving the sibling boundary 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?
Usage is only implied: 'Changes nothing' signals this is the safe read-only option when you just need to enumerate products/plans, and the limit range (1 to 100) constrains how it's called. There is no explicit when-to-use/when-not statement nor a named alternative (e.g. subscriptions_list vs products_list) to route the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Account and go-live overview. Returns whether the account can take live payments, go-live progress, business verification state, the pricing audit state, whether a payout account is connected, and the single next step to take. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's closing 'Changes nothing' is largely reinforcement rather than new information. It does add genuine value by disclosing the full set of facts returned, which is behavioral context not present in the annotations.
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 sentences, front-loaded with the purpose and then a dense but well-earned enumeration of return contents, closed by the mutation guarantee. No filler or repetition.
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?
There is no output schema, so the description carries the burden of describing returns, and it does so thoroughly by naming each returned fact. The only real gap is guidance on how this relates to the sibling verification-status 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 description coverage is 100% and the single 'business' parameter is fully documented in the schema, including the 'omit to act as yourself' semantics. The description adds nothing about the parameter, so the 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 (get) and resource (account/go-live status) and enumerates exactly what the response covers: live-payment eligibility, go-live progress, verification state, pricing audit, payout account, and next step. It is clear enough to distinguish from write tools, but it does not name or differentiate itself from the overlapping agenta_verify_status sibling.
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 phrase 'the single next step to take' implies this is an orientation/diagnostic call used to decide what to do next, which is useful implied guidance. However, there is no explicit when-to-use instruction and no routing away from the closely related agenta_verify_status or agenta_audit_show tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a subscription (at period end by default). Cancels one subscription. By default it stays active until the end of the paid period; set immediately to end it now.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The subscription id | |
| now | No | Cancel immediately instead of at the end of the current period | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds valuable behavioral nuance the annotations do not: cancellation is deferred until period end by default, and immediate termination requires an explicit flag. It does not mention reversibility or authorization requirements.
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, front-loaded with the default behavior the agent most needs. There is mild redundancy between 'Cancels one subscription' and the first sentence, but nothing is padded or buried.
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 mutation with no output schema, the description covers the key behavioral decision (deferred vs immediate cancellation) and annotations cover safety. Missing only edge-case handling (e.g., already-cancelled subscriptions) and auth/business-scope guidance.
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 all three parameters are documented in the schema. The description reinforces the `now` semantics (immediate vs period end) but adds nothing about the `business` acting-on-behalf parameter. Baseline 3 is appropriate when the schema carries the load.
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 ('Cancel a subscription') and clarifies cardinality ('Cancels one subscription'). It does not differentiate itself from siblings like agenta_subscriptions_change_plan, but the core purpose is unambiguous.
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 explains the default cancellation mode (period end) and how to override it ('set immediately to end it now'), which is implied usage guidance. However, it never states prerequisites, when cancellation is appropriate versus change_plan, or what happens if no active subscription exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a subscription to another plan (upgrade charges now, downgrade at period end). Moves one subscription to another plan with the same currency and interval: an upgrade is charged now (prorated), a downgrade applies at period end. Set dryRun to get the price quote without changing anything.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The subscription id | |
| to | Yes | Target plan: the product id (same currency and interval) | |
| dryRun | No | Show the quote only; apply nothing | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the bar is lower, yet the description still adds substantive behavior: upgrade is charged immediately (prorated), downgrade defers to period end, and dryRun returns a quote without mutating. It omits error/failure behavior and permission requirements, so not 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?
The opening two clauses say the same thing twice ('Move a subscription to another plan' / 'Moves one subscription to another plan with the same currency and interval'), which is redundant. The dryRun sentence does earn its place, but the duplication wastes 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 mutation tool with no output schema, the description covers the essential outcome semantics (immediate prorated charge vs. deferred change) and the no-op quote mode. It leaves out failure conditions and any return-value expectations, so it is solid but not exhaustive.
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. The description largely restates what the schema already says for 'to' (same currency and interval) and dryRun ('price quote without changing anything'), adding only marginal interpretation rather than new semantics.
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 ('Move a subscription to another plan'), which is clearly distinct from siblings like subscriptions_cancel and subscriptions_credit. It does not, however, explicitly name or differentiate itself from any sibling tool, which keeps it below 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?
Gives real usage context: the same-currency-and-interval precondition, when an upgrade is charged vs. when a downgrade applies, and the dryRun escape hatch for a quote. It stops short of naming alternative tools (e.g. cancel) or stating when-not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put credit on a subscriber’s account, taken off their next invoice. Adds credit to one subscription, in the plan's currency; it is taken off the subscriber's next invoices. The reason is stored for the merchant only. Returns the credit given.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The subscription id | |
| amount | Yes | Credit to give (e.g. 5.00), in the plan’s currency | |
| reason | Yes | Why you are giving it — for you, not the subscriber | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (not read-only, not destructive, open-world). The description adds real behavioral context: the credit is applied to the next invoice in the plan's currency, the reason is visible to the merchant only, and the call returns the credit given. It omits reversibility/refund behaviour, which is a minor gap for a non-destructive mutation.
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, which is good, but the 'taken off their next invoice' effect is stated twice in near-identical wording, and the return value is repeated from the opening sentence, so the text is somewhat redundant for its length.
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 mutation tool with no output schema, the description covers the essential facts an agent needs: effect timing, currency scope, audience of the reason field, and the returned value. Nothing critical is missing, though error/permission conditions and reversal behaviour would round it out.
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 all four parameters are already documented, including currency, merchant-only reason, and the business acting context. The description restates currency and reason semantics but adds no syntax or format detail beyond the schema, making the baseline 3 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?
Specific verb+resource: 'Put credit on a subscriber's account' and 'Adds credit to one subscription' clearly states the action and the scope (one subscription). It is distinguishable from sibling list/archive tools, though it never explicitly names the neighbouring tools it is not (e.g. discounts_create or subscriptions_credits).
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 description implies the context of use by explaining the effect ('taken off their next invoices') and the merchant-only reason, but gives no explicit when-to-use/when-not guidance or contrast with alternatives such as issuing a discount instead of a credit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Credits given on a subscription, and what is still unspent. Returns the credits given on one subscription and how much is still unspent. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The subscription id | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Changes nothing' is essentially a restatement with no added disclosure. The one genuinely useful addition is the return content ('credits given ... and how much is still unspent'), which partially compensates for the absent output schema, but permissions, pagination, and missing-credit behavior are unaddressed.
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 where one suffices: sentence one ('Credits given on a subscription, and what is still unspent') and sentence two ('Returns the credits given on one subscription and how much is still unspent') are near-verbatim duplicates, and sentence three repeats the readOnlyHint annotation.
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 two-parameter read-only query with full schema coverage and no output schema, the description conveys the essential return shape, which is enough to call it. It stops short of disambiguating the singular/plural credit siblings, leaving a real selection 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?
Schema description coverage is 100% with only two parameters, so the schema fully documents `id` and `business`. The description's 'one subscription' phrasing weakly corroborates `id` but adds no syntax, format, or scoping detail beyond the schema – baseline 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 clear resource and scope: credits for one subscription plus the unspent remainder. It is understandable without opening the schema, but it does nothing to separate itself from the near-identically named sibling agenta_subscriptions_credit, which is the most likely source of mis-invocation.
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?
No when-to-use, no prerequisites, no alternatives named. The agent gets no help deciding between this, agenta_subscriptions_credit, agenta_subscriptions_list, or agenta_subscriptions_change_plan; the 'one subscription' phrasing is the only contextual hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List subscriptions. Returns the merchant's subscriptions with their id, plan, status and subscriber; pass code to see only subscribers who used that discount code. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Only subscribers who typed this discount code | |
| limit | No | Results per page (default 10) | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description nonetheless adds the returned payload shape (id, plan, status, subscriber), which is valuable because no output schema exists, and reinforces non-mutation with 'Changes nothing.' It stops short of covering pagination behaviour implied by 'limit'.
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 sentences, front-loaded with the resource and return fields before the optional filter. 'Changes nothing' is slightly redundant with readOnlyHint but is brief and does not bloat the definition.
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-parameter, all-optional read tool with no output schema and full schema coverage, the definition supplies the resource scope, the filter behaviour and the returned fields. Pagination behaviour and the business-impersonation context are left implicit but are low risk.
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 'code' ('Only subscribers who typed this discount code'), 'limit' and 'business'. The description only restates the filter intent for 'code' and adds nothing about 'limit' pagination or the 'business' impersonation semantics. 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?
States a specific verb and resource ('List subscriptions') and goes further by naming the returned fields (id, plan, status, subscriber). It is immediately distinguishable from mutating siblings such as agenta_subscriptions_cancel and agenta_subscriptions_change_plan.
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 one concrete usage condition - pass 'code' to narrow to subscribers who used a discount code - but offers no explicit when-not guidance and never names an alternative sibling (e.g. customers_list) that might serve a similar need. Usage is implied rather than fully routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The five statements --accept-declaration attests to. Read-only. Returns the five statements a merchant attests to when submitting business verification, the product categories AgentaOS does not support, and what happens if a statement is false.
| Name | Required | Description | Default |
|---|---|---|---|
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description reinforces 'Read-only' but adds nothing beyond that about rate limits, return format, or auth needs. Credit is limited since annotations carry the behavioral burden and the description doesn't extend it.
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 plus a scoping note; front-loaded with the key detail (the five statements and product categories returned). Minor redundancy in restating 'the five statements' twice, but otherwise efficient.
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 simple read-only 1-param tool with rich annotations, the description covers the return shape and scope well. No output schema exists, so describing the returned content in the description is valuable and largely done.
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 single optional 'business' parameter is fully documented. The description adds no parameter-level detail, so 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?
States a specific verb (show/attest) and resource (verification declaration statements), and enumerates the content returned. Distinguishes itself from siblings like agenta_verify_status or agenta_verify_submit by naming the declaration statements, though it doesn't explicitly reference those siblings.
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 read-only framing implies when to call it (to view, not modify), and the context (submitting business verification) hints at usage. But there are no explicit when-to-use / when-not-to-use statements or references to alternative siblings for related tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send back for review after making the changes we asked for. Returns the new state.
| Name | Required | Description | Default |
|---|---|---|---|
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the write nature (readOnlyHint=false), open-world behavior, and non-destructiveness. The description adds one genuinely useful behavioral fact, 'Returns the new state', but says nothing about required permissions, what state transition occurs, or failure/validation behavior for a mutation that feeds a review workflow.
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 sentences, front-loaded with the action and followed by the return-value note; nothing is padded. The phrasing 'the changes we asked for' is informal but compact and informative.
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 low-complexity one-param mutation, the description covers the trigger condition and the response ('new state'), and annotations cover the safety profile. It still omits what happens if resubmission is not allowed in the current state and gives no guidance on the sibling submit tool, leaving a modest 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?
There is a single optional parameter and schema description coverage is 100%, so the schema fully documents the 'business' acting-context semantics (omit to act as yourself). The description adds no parameter meaning beyond that, so the baseline of 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 action (resubmit verification / send back for review) with an implied state transition, which distinguishes it reasonably from agenta_verify_submit. It does not explicitly name any sibling tool, so the agent must infer the boundary from the 'after making the changes we asked for' condition.
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 clause 'after making the changes we asked for' gives an implicit when-to-use condition tied to a prior rejection, but there is no contrast with agenta_verify_submit (initial submission) or any stated prerequisite such as an existing declined verification state. Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where the verification has got to. Returns the business verification state (not started, in review, changes requested, on hold, rejected or verified), with any changes requested and the reason for a hold or rejection. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| business | No | Act for this business you manage (its id). Omit to act as yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Changes nothing' is largely redundant with structured data. However, the description adds real behavioral value by spelling out the return payload — the set of possible verification states plus 'changes requested' and hold/rejection reasons — which matters because no output schema exists.
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, no filler, with the core outcome and the state enumeration front-loaded. The opening 'Where the verification has got to' is colloquial but brief and unambiguous in context.
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 well by listing states and the accompanying reasons. It covers scope (business verification) and the optional-act-as-yourself behavior is handled by the schema. Minor gap: no explicit mention of redirecting to submit/resubmit on a rejected state.
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 'business' parameter is fully documented in the schema (including the omit-to-act-as-yourself semantics). The description adds nothing about the parameter, so the 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 and resource — returns the business verification state — and enumerates the exact state values (not started, in review, changes requested, on hold, rejected, verified). This clearly separates it from the mutation siblings agenta_verify_submit, agenta_verify_resubmit, and agenta_verify_declaration, and from the generic agenta_status_get.
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: 'Changes nothing' signals a read-only lookup and the enumeration of states hints at when the agent would call it, but there is no explicit when-to-use or when-not guidance relative to verify_submit or status_get. Minimum viable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit business verification so the merchant can accept live payments. Sends the business or individual details for review so the account can take live payments. Required: legalName, country, street, city, url, acceptDeclaration true, and registrationNumber when entity is business. Returns the new verification state.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | The merchant project page | |
| city | No | City | |
| entity | No | business | individual (default business) | business |
| postal | No | Postal code | |
| street | No | Registered address | |
| volume | No | under_1k | 1k_10k | 10k_50k | over_50k | |
| country | No | Country of registration, 2-letter code | |
| business | No | Act for this business you manage (its id). Omit to act as yourself. | |
| category | No | saas | digital | services | marketplace | physical | other | |
| delivery | No | instant_digital | email_delivery | subscription_access | manual | scheduled_service | physical_shipped | other | |
| customers | No | The merchant already has paying customers | |
| legalName | No | Registered company name, or full legal name | |
| description | No | One sentence on what it does | |
| displayName | No | Name buyers see on their statement (default --legal-name) | |
| usageClaims | No | The site shows reviews or user counts | |
| addressCountry | No | 2-letter code (defaults to --country) | |
| acceptDeclaration | No | Attest to the five statements and that the merchant sells none of the not-supported categories (agenta verify declaration) | |
| registrationNumber | No | Company registration number (business only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose mutation (readOnlyHint=false), non-destructive and open-world behavior, so the description only needs to add context. It does add that the details are sent 'for review' (i.e., asynchronous adjudication, not instant activation) and that the new verification state is returned, which is meaningful beyond the structured fields. It omits what happens on rejection or whether an existing verification is replaced.
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 goal, but the first two sentences are near-duplicates ('so the merchant can accept live payments' / 'so the account can take live payments'), wasting one of three sentences. The required-field and return-value sentences do earn their 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 an 18-parameter, no-output-schema tool, the definition covers the goal, the mandatory inputs, and the returned state, which is the core an agent needs. It is thin on the many optional parameters (category, delivery, volume, usageClaims) and on the post-submission flow, but the schema carries those fields adequately.
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 goes beyond the schema by naming which fields are actually required (legalName, country, street, city, url, acceptDeclaration, plus conditional registrationNumber), which the JSON schema does not encode since its required list is empty — a genuinely additive correction. It adds no syntax or format nuance beyond that.
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 (submit business verification) with a clear outcome (merchant can accept live payments) and enumerates the fields required. It does not, however, differentiate itself from the close siblings agenta_verify_resubmit or agenta_verify_declaration, so an agent must still infer which of the three to call.
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 goal statement (get the account to live-payment status), and the required-field list tells the agent what a valid call needs. There is no guidance on when to use this versus resubmit/declaration, nor any prerequisite or exclusion (e.g., what to do if a verification already exists).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
agenta_audit_requestagenta_audit_showagenta_businesses_createagenta_businesses_getagenta_businesses_id_linkagenta_businesses_inviteagenta_businesses_listagenta_businesses_revoke_inviteagenta_customers_listagenta_discounts_archiveagenta_discounts_createagenta_discounts_listagenta_discounts_showagenta_invoices_listagenta_invoices_receiptagenta_invoices_send_receiptagenta_pay_checkoutagenta_pay_getagenta_pay_listagenta_products_createagenta_products_listagenta_status_getagenta_subscriptions_cancelagenta_subscriptions_change_planagenta_subscriptions_creditagenta_subscriptions_creditsagenta_subscriptions_listagenta_verify_declarationagenta_verify_resubmitagenta_verify_statusagenta_verify_submit
Add one secure layer between your agents and this server.