GivingFuel MCP by usefulapi

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

Annotations already declare readOnlyHint=false and idempotentHint=false, but the description earns credit by spelling out the concrete consequence: "calling it twice creates two coupons." It also warns the coupon is immediately redeemable in the live account, which is real operational context an agent must consider. It stops short of covering permissions or what the response returns.

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

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

Two dense sentences front-loaded with the WRITE prefix and the endpoint at the tail. Every clause carries information: mutation type, immediacy, cardinality of discount vs. codes, optional constraints, and idempotency warning.

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 write semantics, live-effect risk, idempotency trap and endpoint, which is what an agent most needs before calling. The only real gap is not hinting at what a successful creation returns (e.g., a coupon id) for follow-up calls.

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 name, codes, expires, form_id, currency, available, discount_type and discount_value in detail. The description's summary sentence ("one discount (fixed amount or percent) and one or more codes; optionally limited to…") restates the schema at a high level without adding format or validation nuance, 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?

Opens with an explicit "WRITE: create a discount coupon" verb+resource pair and names the target system (live GivingFuel account), which cleanly separates it from the read/delete coupon siblings. The scope detail (one discount, one or more codes) further pins down exactly what is created.

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

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

The phrase "it can be redeemed by donors right away" tells the agent this is a live, donor-facing effect, and the optional constraints (form, uses, expiry) signal legitimate narrowing. It does not explicitly state when to prefer create vs. reusing an existing coupon via get_coupon/list_coupons, so it falls short of full alternative routing.

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 idempotentHint=true, but the description goes further by stating the concrete blast radius ('codes stop working immediately'), the irreversibility, and the human-approval gate. It also discloses the underlying two-step GET-then-DELETE call pattern, which no structured field conveys.

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, front-loaded with the WRITE marker and the irreversible consequence before the procedural instructions. No filler or repetition of 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?

For a two-parameter destructive tool with no output schema, the description covers the safety gate, the side effects, and the call sequence. It stops short of saying what is returned or how failures (e.g., coupon not found, already deleted) are surfaced, a minor omission given idempotency is annotated.

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 both coupon_id and confirm are formally documented. The description still adds semantic weight by tying confirm: true to the approval workflow rather than treating it as a bare boolean, though it adds nothing about identifier format or behavior on an invalid id.

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?

Opens with a specific verb and resource ('permanently delete a coupon from the live GivingFuel account'), scoping it as a write against production data. It also names the sibling read tool (givingfuel_get_coupon) whose output should precede it, so an agent can place it in the catalog without opening any schema.

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

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

Gives an explicit prerequisite sequence: call givingfuel_get_coupon, show the user the coupon, obtain approval, then invoke with confirm: true. It also implies when not to call, since the destructive effect 'cannot be undone' and codes stop working immediately. The alternative (reading instead of deleting) is named directly.

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, openWorldHint=true, and destructiveHint=false. The description adds useful context by listing the returned data (discounts, codes, availability, redeemed counts) and the endpoint, though it does not cover error or auth behavior.

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

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

Two short sentences with no wasted words. The returned data is front-loaded before the endpoint reference.

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

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

For a simple read-by-id tool, annotations cover the safety profile and the schema fully documents the only parameter. The description also enumerates the returned fields even though no output schema exists, leaving no significant 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?

The single coupon_id parameter is fully documented in the schema, including that it comes from givingfuel_list_coupons. The description only says 'by id' and adds no syntax or format detail beyond the schema, so the baseline of 3 applies at 100% schema coverage.

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: 'One coupon by id' with returned fields including discounts, codes, availability and redeemed counts. The singular 'by id' scope distinguishes it from the list_coupons sibling without opening either 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?

Clearly implies retrieval of a single known coupon, and the schema description points to givingfuel_list_coupons as the source for ids. It does not explicitly state when not to use it or name alternatives in the description itself, but the context is clear.

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 safety is covered. The description adds what comes back (email, billing details, total amount), but says nothing about error behavior for missing ids 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?

Two short sentences, front-loaded with the resource and scope, followed by the return contents and the backing endpoint. 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?

For a single-parameter read with no output schema, the description covers the resource, the lookup key and the returned fields, which is enough for correct invocation. Minor gap is the absence of any mention of not-found behavior.

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

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

Schema coverage is 100% and the schema already explains that customer_id comes from givingfuel_list_customers or an order's customerId. The description's 'by id' adds no meaning beyond that, 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 ('One donor (customer record) by id') and names the returned fields, which separates it from givingfuel_list_customers. It stops short of naming the sibling, but the singular/by-id framing is clear.

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 'by id' framing and the endpoint path imply this is the single-record fetch used after listing, but the description never says when to use it versus givingfuel_list_customers or givingfuel_get_order. Usage is inferable only.

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. The description adds useful knowledge about what the response contains and maps to GET /forms/{id}, but says nothing about not-found/error behavior 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?

Two terse sentences with the resource scope front-loaded and the returned payload enumerated; the endpoint annotation is compact and nothing 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?

With no output schema, the description carries the burden of describing return values and does so by listing the key fields. Error and permission behavior remain unspecified, which keeps it short of 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 coverage is 100% and the schema already documents form_id as 'GivingFuel form id (from givingfuel_list_forms)'. The description's 'by id' adds a scope hint but no new syntax or format detail, 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+resource ('One form by id') and enumerates the returned fields (name, status, accounting reference, time zone, field layout), which distinguishes it from the sibling listing tool givingfuel_list_forms without naming 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?

'One form by id' implies this is the single-record fetch when an id is known, versus givingfuel_list_forms for enumeration, but no alternative or condition is stated explicitly and no prerequisites 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them by enumerating the return fields (path, name, sold, remaining), which fills the gap left by the absent output schema; it stops short of noting empty-inventory behavior.

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

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

One front-loaded clause plus the REST endpoint; every element (resource, qualifier, returned fields, path) earns its place with zero 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 one simple parameter, no nested objects and no output schema, the description covers the essentials, including the returned field set that the missing output schema would otherwise have provided. Only edge cases (form without inventory, empty list, error behavior) 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?

Single required parameter form_id with 100% schema description coverage ('GivingFuel form id.'), so the schema already carries its meaning. The description adds nothing about the parameter — no note on ID format or where to obtain it — leaving this at 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: retrieving inventory items of a form, parenthetically clarified as 'limited-quantity items', plus the exact fields returned. This clearly separates it from givingfuel_get_form and the list_* siblings, though it never names a sibling explicitly to draw the contrast.

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

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

Usage is implied by the resource description — you'd call it when you need sold/remaining counts for a form's limited-quantity items. There is no explicit when-to-use, no exclusions, and no mention of alternatives such as get_form for general form metadata.

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. The description adds real context beyond that: exactly which facets of the order come back, that the call maps to GET /search/orders/{id}, and that transactions are only included on request — though it says nothing about auth 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?

Two sentences, zero filler: the returned data is front-loaded, the optional embed flag is explained second, and the underlying endpoint is appended as a compact anchor. Nothing repeats the schema verbatim.

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 present, the description carries the burden of describing return values and does so at the field-group level. The internal shape of the embedded transactions or billing details is left implicit, which is a small residual gap for a read tool with annotations covering safety.

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 earns a bump by clarifying that include_transactions embeds the order's payments, specifically charges and refunds — a semantic detail the schema's 'Also return the order's transactions' does not convey.

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

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

States a specific verb (get) and resource (a single order by id) and enumerates the payload it returns: billing details, form, totals, status. That distinguishes it from givingfuel_list_orders and givingfuel_get_transaction without naming them explicitly, 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?

The description implies the lookup usage (fetch one order by id) and tells the caller how to opt into embedded payments, but it never states when to prefer this over givingfuel_list_orders or givingfuel_get_transaction, nor any prerequisite. Usage is inferable but not spelled out.

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, so the safety profile is covered. The description adds real value by spelling out the returned payload (amount, schedule, status, last/next payment, payments remaining), which matters because there is no output schema; it does not mention behavior for an unknown id though.

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

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

Two short fragments, front-loaded with the core identity and the field list; essentially no waste. The trailing endpoint path is marginally redundant for an agent but does no harm; the clipped phrasing borders on telegraphic.

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, listing the returned fields is exactly the compensation needed, and the single parameter is fully documented in the schema. Only gap is not-found/error behavior for an invalid id, which is minor for a simple read tool.

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

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

Schema description coverage is 100%, and the schema already documents subscription_id including its origin tool and positivity constraint. The description adds nothing further about the parameter, 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 resource (one recurring donation/subscription) scoped by id, and enumerates the fields returned, which clearly separates it from the list-style sibling givingfuel_list_subscriptions. It never names the sibling explicitly, so differentiation is implicit rather than explicit.

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?

"by id" implies the lookup case (you already have an id, presumably from listing), and the schema points back at givingfuel_list_subscriptions. But the description itself gives no explicit when-to-use/when-not or prerequisite 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 and destructiveHint=false, so safety is covered; the description adds genuine value by disclosing the returned field set (including 'masked card', signaling PII is redacted) in the absence of an output schema. It stops short of describing error behavior for unknown ids or any pagination/rate considerations.

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 verb+resource and then the returned fields, ending with the underlying endpoint. 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?

For a single-parameter read tool with no output schema, listing the response fields fills the main gap an agent would have. Minor omissions remain (not-found behavior, whether any fields can be null), but nothing needed to invoke 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%, with transaction_id documented including its provenance ('from givingfuel_list_transactions'). The description adds nothing about the id beyond 'by id', so the schema carries the full load and baseline 3 applies.

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

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

Names a specific verb and resource ('one transaction by id') and enumerates the payload it returns (amounts, type, payment method, masked card, gateway message, status), which makes the fetch-single semantics unmistakable. It doesn't explicitly contrast itself with givingfuel_list_transactions, so sibling differentiation is only implied by 'by id'.

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

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

Usage is implied rather than stated: 'one transaction by id' signals a single-record lookup, and the schema description points to givingfuel_list_transactions as the id source. No explicit when-to-use/when-not guidance appears in the description itself.

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. The description adds useful behavioral context by naming the returned fields (discounts, codes, availability, redeemed count, expiry) and the underlying GET endpoints, though it does not discuss pagination behavior.

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

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

Two tight sentences, front-loaded with the core list operation and scope distinction. The return fields and endpoint paths are packed efficiently with no redundant or filler text.

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 a fully documented schema and safety annotations, the description covers the essential gaps: scope selection, returned fields, and endpoints. No output schema exists, but the description sufficiently explains what the caller will see.

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 five parameters are already well documented. The description reinforces the form_id distinction but adds no syntax, format, or edge-case meaning 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?

The description states a specific verb and resource ('List GivingFuel coupons') and immediately distinguishes the two scopes: account-wide coupons versus coupons for a single form when form_id is supplied. This clearly separates it from sibling tools like get_coupon and create_coupon without needing to inspect 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 explains the key selection context: omit form_id for global coupons or provide it to scope results to one form. However, it does not explicitly name alternatives such as get_coupon for retrieving a single coupon, nor does it state when not to use this list operation.

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, destructiveHint=false), so the key added value is the eventual-consistency warning that new donors can take up to 5 minutes to appear — non-obvious and operationally important. The raw endpoint path is a minor extra, and pagination behavior is left to the 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: resource and payload first, then filtering, then the freshness caveat. Every clause carries information; nothing 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?

With no output schema, the description compensates by naming the returned fields, and pagination plus limits are fully covered by the schema. Only the missing routing against get_customer keeps it from being complete for an 8-parameter list 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 every parameter including the cursor, sort, and date bounds is already documented. The description only restates the email and date filters and adds no syntax, format, or interaction 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 the specific verb and resource ('List customer records (donors)') and enumerates the returned fields, so the agent knows exactly what comes back. It does not explicitly differentiate itself from the sibling givingfuel_get_customer, which partly overlaps via the email filter.

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 via 'Filter by email or dates', giving a rough sense of when to use it, but never says when to prefer givingfuel_get_customer for a single-record lookup vs. this listing tool. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description usefully adds the concrete return shape and that status is either 'open' or 'closed', plus the underlying GET /forms endpoint. It omits pagination behavior, but the schema's cursor field already covers that.

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 zero filler; the resource and return fields are front-loaded before the usage hint and endpoint. Every clause carries information.

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

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

With no output schema, the description compensates by naming the returned fields and the status values, which is what an agent needs to use the result. Pagination via next_starting_after is left to the schema, a minor but real 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 seven parameters (sort, limit, date filters, cursor) are already documented in the schema with defaults and bounds. The description adds no parameter-level meaning beyond that, which matches 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?

States a specific verb and resource ('List the account's GivingFuel forms') and enumerates the returned fields (id, name, status, created/updated dates), which pins down scope precisely. It never names the closest sibling, givingfuel_get_form, so the single-vs-list distinction is only inferable from the verb.

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 sentence 'Use the form ids to filter orders, transactions and subscriptions' gives a downstream usage hint, but it never states when to call this instead of givingfuel_get_form or the other list_* tools. Usage is implied rather than prescribed.

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, so the safety profile is covered. The description adds the endpoint (GET /search/orders) and default sort direction, but says nothing about pagination behavior, rate limits, or result-size expectations for a full listing.

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 dense sentences with no filler: scope and returned fields first, filters and endpoint second. Every clause carries information an agent would otherwise have to infer.

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, which is what an agent needs. It stops short of explaining paging (cursor via starting_after, limit 1-50) or ordering details beyond 'newest or oldest first', leaving a small gap for a 12-parameter list 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 coverage is 100%, so all 12 parameters are already documented in the schema. The description's filter list mirrors those parameters without adding format, syntax, or precedence details, which is the correct baseline 3 when the schema carries the load.

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

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

States a specific verb and resource ('List donation orders'), disambiguates the record grain ('one per checkout'), and enumerates the payload fields returned (order number, billing name/address, form, total, currency, status). An agent can tell this apart from givingfuel_get_order and givingfuel_list_transactions 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?

The clause 'Filter by form, status, donor email, customer id, order number or dates' implies when the tool is useful, but there is no explicit guidance on when not to use it or which sibling to pick instead (e.g., get_order for a single known order). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete payload shape (amount, schedule, status, dates, donor email) and the underlying endpoint, but says nothing about pagination behavior or result limits — though the schema covers those, so a 3 is fair.

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 dense sentences, front-loaded with the resource and payload, followed by filters and the endpoint. Every clause carries information; the only minor cost is the crammed enumeration style.

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's field enumeration is genuinely valuable, and the read-only annotations cover safety. It's close to complete for a filtered-list tool; only pagination/return-envelope context is left implicit.

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

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

Schema description coverage is 100%, so every one of the 15 parameters is already documented. The description's filter sentence roughly restates a subset of the schema without adding syntax, formats, or priority, so it hits the baseline rather than adding meaning.

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 recurring donations (subscriptions)') and enumerates the returned fields, so an agent knows exactly what this returns. It doesn't explicitly differentiate itself from the sibling get_subscription (single record vs. list), leaving that inference to the agent.

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?

Lists the filter dimensions ('Filter by form, status, donor, or next/last payment date'), which implies search/browse use, but gives no explicit when-to-use or when-not-to-use guidance and never names the read-one alternative (get_subscription).

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, openWorldHint=true, destructiveHint=false, so the safety profile is covered by structured data. The description adds the underlying endpoint (GET /search/transactions) and the returned field set, but says nothing about pagination behavior, result ordering, or rate limits beyond what the schema already documents via starting_after and sort.

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 dense sentences with no filler: the first front-loads what the tool returns, the second covers filtering, and the endpoint is tacked on last as a compact reference. Every clause carries information.

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

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

With 16 optional parameters, no output schema, and full schema descriptions, the description is complete enough for correct invocation, and it usefully compensates for the missing output schema by listing returned fields. It stops short of covering pagination semantics and default ordering, which an agent would need for multi-page iteration.

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 all 16 parameters carry their own descriptions, so the schema does the heavy lifting. The description's filter list (type, method, form, order, donor, dates) merely restates a subset of the schema's parameters without adding syntax or format detail, 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?

Names a specific verb and resource ('List payment transactions (money movements)') and enumerates the returned fields (amount, deductible amount, currency, type, payment method, masked card, status, form, donor email), so the agent knows exactly what resource this is. It does not explicitly contrast with get_transaction or list_orders, so it falls just short of 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 second sentence tells the agent what can be filtered (type, method, form, order, donor, dates), which implies when the tool is appropriate, but there is no explicit when-to-use or when-not guidance and no named alternative for single-record lookups (get_transaction). Usage is inferable rather than stated.

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