AgentaOS

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

Annotations establish the safety profile (readOnlyHint=false mutation, destructiveHint=false, openWorldHint=true). The description adds genuinely useful context beyond that: it explains this is a free, non-blocking, written review. It does not cover auth/permission needs or return behavior, keeping it short of a 5.

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

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

Front-loaded with the purpose, but repeats 'free Revenue & Pricing Audit' twice in the first two sentences, which is redundant. The wording earns most of its place but could be tighter.

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 submit-style tool with no output schema and full schema coverage, the description is nearly complete: it explains what happens on success (starts a written review) and points to agenta_audit_show for tracking progress. No mention of follow-up actions or limits, but nothing critical is missing.

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

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

Schema description coverage is 100% and every parameter is documented in the schema, so the baseline is 3. The description only restates that url is required, adding no format or constraint detail beyond the schema.

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

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

States a specific verb (ask for / starts) and resource (Revenue & Pricing Audit, a written review of pricing and checkout), and distinguishes itself from the sibling agenta_audit_show which is for checking progress. An agent can tell what this does 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?

Explicitly gives the triggering condition (when the merchant wants the audit of a page where they sell) and names the alternative sibling agenta_audit_show for progress. It also clarifies the audit does not block going live, which helps the agent decide to request it. No explicit when-not guidance, though.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and the description reinforces this with 'Changes nothing.' Beyond annotations it adds the return contract (requested flag, state, grade, PDF link) and the conditional nature of the PDF, which is genuine added value. No rate limits or state-transition guidance.

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 read action, then the return values, then the alternative routing. Little waste, though the opening fragment is grammatically loose.

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-param, read-only tool with no output schema, the description covers the outcome shape (requested/state/grade/PDF link) and the behavior change on download. It omits any state vocabulary or indication of what to do when the audit is still pending, which is the main remaining 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 all three parameters (output, business, download) are already documented in the schema, including the terminal-vs-tool-call distinction for 'download'. The description echoes the download/PDF behavior but adds no syntax or semantics the schema lacks; 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 a specific resource (pricing audit) and both actions (read state, download report PDF), and explicitly distinguishes itself from agenta_audit_request. The opening sentence is a fragment ('The audit state, and download the report PDF once it exists'), which slightly blurs whether the tool reads or downloads, but the second sentence clarifies both.

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 a clear use condition and names the alternative sibling: 'If none was requested, use agenta_audit_request.' That is an explicit routing rule. It stops short of full coverage — nothing about polling/retrying while the audit is still in progress — so it is strong but not exhaustive.

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

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

Annotations 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.

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.

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.

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.

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 that. The description does add genuinely useful context beyond the annotations: the shape of the return (id, name, status) and the cross-tool convention that the returned id is reused as the 'business' parameter elsewhere.

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 action and scope, then the return shape, then the cross-tool usage pattern. Nothing is padded; the only near-redundant clause ('Changes nothing') is one short 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?

There is no output schema, so the description carries the burden of describing returns and it does so (id, name, status). With zero required parameters, a read-only safety profile in annotations, and no nested structures, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and the single 'business' parameter is already documented in the schema ('Act for this business you manage (its id). Omit to act as yourself.'). The description's note about passing a business id to other tools reinforces that meaning but adds no syntax or format 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?

States a specific verb and resource ('List the businesses you manage') and defines the scope precisely: businesses this account manages, i.e. its clients or other apps. It even names the returned fields (id, name, status), so an agent can distinguish it from agenta_businesses_get or agenta_businesses_create without opening a schema.

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

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

It tells the agent what to do with the result: 'Pass a business id as business on any other tool to act for it', establishing this as the discovery entry point. It does not explicitly contrast with agenta_businesses_get or state exclusions, so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description still adds value: it specifies what is actually destroyed ('the open invitation ... its link stops working') and adds a consent requirement ('Ask the merchant'), neither of which is expressible 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?

Front-loaded and short, but the first two sentences restate the same action ('Withdraw your client's open invitation' / 'Withdraws the open invitation of one managed business'), which is redundant rather than additive. The caution sentence earns its place; the duplication does not.

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 revoke tool with no output schema and annotations that carry the safety profile, the description covers the action, its consequence, and the consent prerequisite. It is essentially complete, with only the lack of alternative-tool routing as a 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% and both parameters are documented in-schema, so the baseline is 3. The description adds no format, default, or interaction detail for 'id' or 'business' beyond what the schema already 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+resource ('Withdraw your client's open invitation') and clarifies the effect ('so its link stops working'), which implicitly distinguishes it from the inverse sibling agenta_businesses_invite. It does not, however, explicitly name or contrast any sibling tool, so it falls just 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 instruction 'Ask the merchant before calling this' gives a real prerequisite/caution, which implies the operational context. But it never states when to use this versus alternatives (e.g., re-inviting via agenta_businesses_invite) or any exclusion conditions, so guidance remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint=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.

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 safety profile is partly covered. The description still adds substantive context beyond that: the effect is forward-looking only and does not retroactively revoke discounts already used, plus the merchant-consent requirement.

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 impact statement is front-loaded and the total length is short. There is mild redundancy between the first two sentences ("Stop a discount code working" / "Stops one discount code working"), but the second sentence still adds the scope detail and the third adds the caution.

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, id-based operation with no output schema, the description covers the key concerns: what changes, what does not change, and the consent precondition. It omits whether the operation is reversible and any error/authorization behavior, but the annotations carry the destructiveness signal.

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

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

Schema coverage is 100% with only two parameters, both documented in the schema (id and optional business). The description adds nothing about parameter semantics, 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 description names a specific action (stop a discount code from working) on a specific resource (a discount code), which clearly separates it from sibling tools like agenta_discounts_create, agenta_discounts_list, and agenta_discounts_show. It is clear but does not explicitly name or contrast with 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?

"Ask the merchant before calling this" gives an explicit consent prerequisite, and the note that only new purchases are affected while existing subscribers keep their discount defines the effect scope. It stops short of naming an alternative (e.g., re-enabling or editing a code), so it lacks explicit when-not guidance.

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

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

Annotations already declare 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.

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.

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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Changes nothing' largely restates them. The added value is the return-field inventory (id, amount, currency, status, buyer), which the annotations do not convey and which substitutes for the absent 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 short sentences, front-loaded with the action and payload, followed by the safety note and the sibling hand-off. No filler and nothing that duplicates the schema at 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 read-only list tool with no output schema, the description covers what is returned, the cap, and the next-step tools. Minor gaps remain (no mention of paging behavior beyond limit, or of default ordering), but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (limit, business) are already documented in the schema. The description repeats the limit bounds (1 to 100) and adds no new meaning for the business parameter, so it does not exceed the structured 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+resource ('List invoices') and enumerates what is returned (id, amount, currency, status, buyer), which lets an agent recognize the payload without an output schema. It also distinguishes itself from the per-invoice siblings by telling the agent that an id from this list feeds agenta_invoices_receipt / agenta_invoices_send_receipt.

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 clear context: use this to enumerate invoices, then pass an id to the receipt or send_receipt tools. It stops short of stating when NOT to use it (e.g. vs. a filtered lookup or other list tools), but the sibling routing is explicit and actionable.

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

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

Annotations already declare readOnly/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.

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.

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

Annotations only declare the mutation and open-world profile; the description adds genuinely useful behavior beyond that: the returned checkoutUrl/sessionId/expiry, that the buyer pays by card, and that tax is added by AgentaOS. It stops short of stating auth/permission requirements or whether the session can be cancelled or re-issued.

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 core action and value of the return payload. The opening 'Create a checkout session. Creates a one-off checkout...' is mildly redundant, but nothing else is wasted.

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

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

With no output schema, the description correctly carries the return-value burden (checkoutUrl, sessionId, expiry) plus payment and tax behavior, which is enough for a five-parameter tool. It leaves out error/expiry handling and currency defaults, minor gaps.

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 each of the five parameters is documented inline, so baseline 3 applies. The description only echoes amount ('for an amount') and adds no meaning for email, currency, business, or description beyond what the schema already says.

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 checkout session') and immediately narrows scope to 'a one-off checkout for an amount', which separates it from the subscription siblings. An agent can act on this 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?

It provides a clear follow-up path ('Follow up with agenta_pay_get') which gives some routing signal, but never states when to use this tool versus alternatives such as agenta_products_create or the subscription tools, nor any exclusions or prerequisites. Usage is implied rather than explained.

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

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

Annotations already cover the safety profile (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.

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.

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 that the call returns the product id and a shareable buyer link, which is genuinely useful since there is no output schema. It still omits auth requirements or rate limits, so a 3 is appropriate.

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-loads the verb and resource, and each sentence conveys usable information. There is mild redundancy between the first two sentences ('one-time product or a subscription plan' repeated), which keeps it from 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?

For an 11-parameter creation tool with no output schema, the description covers both what is created and what is returned, plus how to consume the id. Nothing critical is missing, though deeper behavioral notes would be needed for a 5.

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. The description reinforces the interval/subscription concept but adds no syntax or format detail beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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 product') and explicitly distinguishes the two output modes it produces: a one-time product versus a subscription plan with an interval. An agent can identify it apart from siblings like agenta_products_list without opening the schema.

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

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

Gives downstream routing ('Use the id with agenta_pay_checkout or as a plan for agenta_subscriptions_change_plan'), which clarifies the follow-on context. However, it does not state when to prefer this over alternatives or any prerequisites, so it stops short of explicit when/when-not guidance.

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

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

Annotations already declare 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, and 'Changes nothing' largely restates that safety profile. However, with no output schema, the enumeration of the exact response fields adds genuinely useful behavioral context about what the call surfaces.

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 a short overview phrase and 'Start here' imperative, then a compact field list. Every sentence contributes, though the field enumeration is slightly list-like rather than tight prose.

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 burden of telling the agent what comes back and does so comprehensively. Annotations cover the safety profile and the schema fully documents the lone parameter, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100% and the single optional 'business' parameter is fully documented in the schema, so the baseline is 3. The description adds no additional semantics about acting on behalf of a business versus acting as oneself.

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 ('Account and go-live overview') and enumerates exactly what the call returns (live-payment capability, go-live progress, verification state, pricing audit state, payout connection, next step). 'Start here' carves out a distinct entry-point role relative to siblings like agenta_verify_status.

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?

'Start here' gives clear first-call context, telling the agent to use this before drilling into more specific tools. It does not name any alternative (e.g., agenta_verify_status) or state exclusions, so it falls short of explicit when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds substantive context beyond that: cancellation is deferred to period end by default, the subscription stays active until the paid period ends, and merchant consent is expected. It does not say whether the cancellation is reversible or what happens to outstanding credits, which keeps it out of 5 territory.

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 default behavior is front-loaded and the sentences are short and mostly non-redundant. 'Cancel a subscription' and 'Cancels one subscription' are slight restatements, but nothing is 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?

For a destructive, single-parameter mutation with no output schema, the description covers default timing, the immediate override, and the consent expectation. It omits post-cancellation effects (reinstatement, refunds), so an agent has enough to call it correctly but not a complete picture of consequences.

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 id, now and business in full. The description reinforces the semantics of 'now' ('set immediately to end it now') but adds nothing about the `business` acting-on-behalf parameter. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Cancel a subscription') and clarifies the scope ('Cancels one subscription'), which an agent can distinguish from list/change_plan siblings. It does not explicitly name or route away from the other subscription tools, but the purpose itself 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 gives a concrete precondition ('Ask the merchant before calling this') and explains the default vs. immediate choice, which is real usage guidance. It stops short of naming alternatives such as changing a plan instead of cancelling, so it does not reach a 5.

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

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

Annotations already declare 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.

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.

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.

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

Annotations already mark this readOnlyHint=true and destructiveHint=false, so the description's burden is reduced. It still adds value by confirming 'Changes nothing' and describing the returned shape. It does not mention pagination behavior despite a limit parameter with a maximum, which is the main remaining gap.

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 action and its return shape, followed by the optional filter and the downstream id usage. Every clause carries information and none is padding.

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

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

With no output schema, the description usefully enumerates the returned fields, and it covers the filter parameter. It omits pagination/limit semantics, which matters for an unbounded read on subscriptions, so it is close to but not fully complete.

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

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

Schema description coverage is 100%, so all three parameters are already documented with defaults and bounds. The description only re-states the code filter and says nothing about limit or business, so it adds no meaning beyond the schema — the correct baseline of 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 verb+resource ('List subscriptions') and goes further by enumerating the returned fields (id, plan, status, subscriber), which tells an agent what it will actually get. It does not explicitly distinguish itself from the nearby sibling agenta_subscriptions_credits, 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?

Gives a concrete filter condition ('pass code to see only subscribers who used that discount code') and routes the agent to the follow-up tools that consume an id (cancel, change_plan, credit). It lacks explicit when-not-to-use guidance or a pointer to the related credits/credits-listing sibling, so it is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'Read-only' statement is largely redundant. However, the description adds real value by enumerating the return payload (the five statements, unsupported categories, false-statement consequences), which the absent output schema otherwise leaves undisclosed. The openWorldHint=true is not addressed.

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 content is front-loaded and there is little filler, but the opening fragment 'The five statements --accept-declaration attests to.' is awkward and would confuse a reader skimming the first clause. A small edit would make the whole entry tighter.

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 burden of describing the return value and does so reasonably well (three categories of returned content). For a simple read-only, zero-required-param tool, this is close to sufficient; a note on formatting or pagination would complete 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% and the single 'business' parameter (optional, omit to act as yourself) is fully documented in the schema. The description adds nothing about it, 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?

Specific verb-resource pair: it returns 'the five statements a merchant attests to when submitting business verification,' plus the unsupported product categories and the false-statement consequences. An agent can distinguish this read-only declaration viewer from sibling write tools like agenta_verify_submit 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?

Explicit sequencing guidance: 'Show these to the merchant before calling agenta_verify_submit with acceptDeclaration true.' This names the alternative tool and the condition that triggers it, leaving nothing to inference.

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

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

Annotations declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new context: the required source state, the merchant precondition, and that the new state is returned. It does not mention auth/permission needs, which is a minor gap.

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 second sentence restates the action ('sends it back for review') already conveyed by the opening clause, making the text partially redundant. Trimming the repetition would yield a tighter 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 one-parameter mutation with no output schema, the description covers the state precondition, the triggering condition, and that the new state is returned. Only permission/scope details are absent, which is a modest omission.

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?

Single optional 'business' parameter with 100% schema coverage; the schema already explains the act-as-business semantics and the omit-to-act-as-yourself default. 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?

Names a specific action (resubmit verification for review) and differentiates implicitly from the sibling agenta_verify_submit by scoping to the post-changes state. The phrase 'send back for review' is slightly ambiguous (could read as returning to the merchant), but the follow-up clause clarifies intent.

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

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

Gives an explicit precondition: only when verification is in the changes-requested state AND the merchant has made the changes. It does not, however, name the alternative tool (agenta_verify_submit) or state what to do in other states, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true. The description reinforces this in plain language ('Changes nothing') and adds real value by disclosing the return surface — the state set plus changes requested and hold/rejection reasons — which is not in any structured field.

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

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

Three compact sentences: outcome first, disclosure of return values second, sibling routing last. No filler, and the most important fact is front-loaded.

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 and a trivial input schema, the description carries the return-value burden and does so by enumerating states and mentioning reasons. It stops short of describing format or pagination, but for a single-business status read 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% and the single business parameter is fully documented there, including its optional semantics. The description adds nothing about the parameter, 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 description names a specific verb and resource ('Returns the business verification state') and immediately differentiates itself from the sibling agenta_status_get. It also enumerates the possible states, so an agent knows exactly what this tool reports 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?

It explicitly routes one alternative case ('For the whole go-live picture use agenta_status_get'), which is the closest sibling. It gives no guidance on the verify_submit/resubmit/declaration siblings or prerequis ites, so the when-to-use picture is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds process context beyond that: the details go to a review queue and the call returns the new verification state. It does not say what happens on rejection, how long review takes, or whether submission can be undone short of resubmitting.

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

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

Four sentences, but the first two are near-duplicates ('so the merchant can accept live payments' / 'so the account can take live payments'), which wastes the highest-value position. The required-field list and the declaration prerequisite are front-loaded reasonably well.

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 mutation with no output schema, the description covers the action, the prerequisite, the required subset, and the return value shape. Remaining gaps are the undocumented optional parameters and the review/approval lifecycle, which the schema text carries only partially.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds information the schema does not carry: the required field set (legalName, country, street, city, url, acceptDeclaration) and the conditional requirement of registrationNumber when entity is business. This materially compensates for the schema's empty required list.

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 and resource (submit business verification) plus the business outcome (accept live payments). It names agenta_verify_declaration as a related sibling, but does not distinguish itself from agenta_verify_status or agenta_verify_resubmit, so an agent must still infer the boundary.

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

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

It states the enabling condition (so the account can take live payments) and imposes an explicit sequencing rule: only set acceptDeclaration after the merchant has read agenta_verify_declaration. There is no guidance on when to use this versus verify_status/verify_resubmit, but the prerequisite routing is genuinely useful.

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