representments.com

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context. "The first one free" does add useful commercial context (subsequent responses appear to be paid), but the description never says what the tool actually produces or whether it depends on an external merchant account.

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

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

Three short sentences, no filler, and the audience/condition (merchant with an open chargeback) is front-loaded. Slightly informal tone ("the first one free") trades some precision for compactness, but nothing 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 two optional parameters, no output schema, and full annotation coverage, the remaining gap is the return behavior: an agent cannot tell whether it gets prose guidance, a generated draft, or a redirect. For a guidance-style tool that ambiguity matters, and the description does not resolve 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 both parameters are documented with examples (13.1, Visa 10.4) and network enum values. The description only echoes optionality with "if you know it," adding 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?

"Explains how to get a custom response" gives a rough sense of the resource (dispute-response guidance), but the phrasing is vague — it is unclear whether the tool returns explanatory text, a generated response draft, or a link. Siblings like get_pricing and lookup_reason_code are not referenced, so the boundary between this tool and reason-code lookup is left implicit.

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

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

"For a merchant with a chargeback open now" is a usable precondition, and "Pass the reason code if you know it" signals the optional path. However, no alternative is named and there is no guidance on when to use lookup_reason_code first to obtain the code this tool accepts.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safe, static read profile is covered. The description adds that the price list covers specific tiers and currency, which is useful content context, but says nothing about whether the data is cached, region-specific, or subject to change — beyond-annotation value is modest.

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?

A single front-loaded sentence with no filler. The trailing clause 'per-case work for a single chargeback of $10,000 or more' is grammatically ambiguous — it is unclear whether $10,000 is a price or a minimum case size — which costs it the top mark.

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-argument, read-only lookup with no output schema, the description gives enough to know what categories of pricing come back and in what currency. It does not list actual amounts or the two plan names, but enumerating those is the call's job, not the description's.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description's mention of USD implicitly clarifies that no currency parameter is expected.

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 the specific resource (representments.com pricing) and the currency (USD), and enumerates the three price categories returned: the free first response, two monthly plans, and per-case work. An agent can tell this apart from the sibling reason-code and help tools without opening the schema. Slightly weaker than a 5 because it is written as a noun fragment rather than 'Returns pricing for...'.

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 guidance on when to call this versus doing something else, and no statement of preconditions. The sibling tools (get_help_with_a_dispute, list_reason_codes, lookup_reason_code) are unrelated, so the risk of misrouting is low, but the description offers no explicit usage cue at all.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds useful context the annotations don't: the payload shape (name plus link) and the fact that it covers only the codes representments.com explains, which implies an incomplete catalog relative to the networks' full code lists.

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

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

Two sentences, front-loaded with what is listed and what each item contains, followed by the filter instruction. No filler.

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

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

With no output schema, the description usefully discloses the returned fields and the catalog scope, which is what an agent needs. It stops short of saying how many codes exist or whether results are exhaustive per network, but nothing essential is missing.

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

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

Schema coverage is 100% and the schema description already enumerates the four allowed networks, so the description's mention of the same four values adds little beyond what is structured. The filtering semantics ('see only its codes') is the only marginal addition.

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 (lists) and resource (chargeback reason codes) scoped to four named networks, and says what each entry contains (plain-English name plus link). This is distinguishable from the sibling lookup_reason_code, which implies single-code detail.

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?

'Pass a network to see only its codes' gives the filtering behavior, so the optional-parameter usage is implied. However, it never says when to use this versus lookup_reason_code or get_help_with_a_dispute, so routing still requires 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description earns credit by disclosing the substance of the response — the customer's claim, the evidence that wins, typical origin situations, and a source link — which matters because no output schema exists. It omits what happens for an unrecognized code, 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?

Two sentences, zero filler, with the capability stated first and the accepted input forms second. 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?

With only two fully documented parameters and no output schema, the description covers the essentials by describing what the returned explanation contains and which input shapes are valid. Only the error path for an unknown or malformed code is left 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 coverage is 100%, so baseline would be 3, but the description adds real value by listing accepted formats beyond the schema's examples: numeric codes like 4853 and alphanumeric ones like C08, plus network-prefixed forms such as "Visa 10.4". That signals the code field tolerates embedded network identifiers, which the schema does not state.

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?

"Explains one chargeback reason code" gives a specific verb and a singular resource, and the enumerated payload (claimed reason, winning proof, typical situations, link) makes clear this is a detail lookup, not a listing. The word "one" implicitly separates it from list_reason_codes without needing to name it.

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: an agent infers it should call this when it already holds a specific code and wants detail. There is no explicit statement about when to prefer list_reason_codes or get_help_with_a_dispute instead, and no prerequisites or exclusions are given.

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