Qgiv MCP by usefulapi

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

Annotations already declare the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds real content context the annotations cannot: results are summary-only with per-transaction rows deliberately omitted, which tells the agent not to expect line-item detail.

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 that states the resource ('latest statement(s)'), the output shape ('summary totals'), the key exclusion ('per-transaction rows left out'), and the endpoint. No filler or restatement of the title.

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

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

With no output schema, the description must carry return-value meaning, and it only partly does — it says summary totals without describing what a statement record contains. More importantly, it says the target is 'the organization or form' yet the schema has no parameters, so how the scope is selected (auth context? default?) is left unexplained. Adequate but with a clear 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 tool takes zero parameters, so there is no parameter semantics for the description to carry — the baseline for a 0-param tool is 4. Nothing is missing on this dimension.

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: retrieves the 'latest statement(s)' with 'summary totals' and explicitly notes per-transaction rows are excluded, so the agent knows exactly what it gets. However, it never distinguishes itself from siblings like qgiv_get_statement (singular) or qgiv_list_statements, leaving the 'why this one' question open.

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 word 'latest' implies a recency-based retrieval distinct from list_statements, which suggests when an agent would reach for this tool. But there is no explicit when-to-use, no exclusion, and no pointer to any alternative sibling — usage is inferred 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description nonetheless adds genuinely useful context: the underlying call is a POST to /pledges/{id} that sends no package, so despite the write-style HTTP verb nothing is mutated. That resolves a potential agent confusion the annotations alone do not.

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, front-loaded with the purpose and followed by the one non-obvious operational fact. 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?

There is no output schema, so the description is the only place that could convey what a 'pledge option' record contains. It does not, leaving the agent without any expectation of the return shape. Everything needed to make the call is present, but return-value context 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% with a single documented integer pledge_id, so the schema carries the semantics. The description's 'by id' merely restates the parameter rather than adding format or lookup behavior beyond it. 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 resource and scope: 'One pledge option by id.' An agent can distinguish this from qgiv_list_pledges by the singular scope, though the phrase 'pledge option' is slightly unusual and the description never uses the tool's own verb ('get').

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

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

No explicit when-to-use or when-not-to-use guidance. The 'by id' phrasing implies the alternative (listing) without naming qgiv_list_pledges, leaving the agent to infer the selection condition.

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, idempotentHint, and destructiveHint=false, so safety is covered; the description reinforces this with 'read-only; schedules cannot be changed here'. It adds the underlying endpoint (POST /reporting/recurring/{id}), a minor behavioral detail, but says nothing about the response payload or what fields a schedule contains.

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?

It is a single compact sentence with the key identity and scope front-loaded and zero filler. The trailing endpoint string is of marginal value but costs little 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 simple two-parameter read with full annotation coverage, the essentials (single schedule, by id, read-only) are present. With no output schema, however, the description could have stated what a schedule returns or noted the include_contact default's effect on output, leaving a modest gap.

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

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

Schema description coverage is 100%, so both recurring_id and include_contact (including the 'off by default' behavior) are already fully documented in the schema. The description adds no parameter-level information beyond identifying the lookup key, 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 states a specific verb (retrieve/get) and resource (one recurring donation schedule) with a scoping constraint (by id), which cleanly separates it from the sibling qgiv_list_recurring_schedules. It does not name the sibling explicitly, so it falls just short of full sibling differentiation.

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 when this is appropriate (fetch a single schedule by id, read-only) and adds a caution that schedules 'cannot be changed here', which steers the agent away from expecting mutation. There is no explicit when-to-use/when-not guidance or named alternative for cases like listing or updating schedules.

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, so the safety profile is covered structurally. The description reinforces read-only scope ('this server never issues refunds') and adds the endpoint, but nothing about the return shape, pagination, or behavior on an unknown id. The 'POST' mention alongside a read-only operation is transport detail, not a contradiction of 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?

Very short and front-loaded, with no filler sentences. It is slightly telegraphic (parenthetical plus a bare endpoint path), but 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 would ideally say what 'in full' returns or how a missing id is handled. It gives a hint ('in full') and the annotations cover safety, so the gap is moderate rather than severe.

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 both parameters are documented there, including the include_contact default behavior. The description only echoes 'by id' for refund_id and adds nothing about include_contact, so baseline 3 applies 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+resource+scope: fetch one refund in full by its id. This implicitly differentiates it from the sibling list tools (qgiv_list_recent_refunds, qgiv_list_refunds_by_date), but never names them explicitly, so the contrast is inferable rather than stated.

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 clarifies a when-not ('this server never issues refunds'), which prevents an agent from attempting a write. However, it does not say when to prefer this over qgiv_list_refunds_by_date or qgiv_list_recent_refunds; the selection logic is only implied by 'one ... by id'.

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/idempotentHint/destructiveHint=false, so the bar is lower, yet the description adds real context: contact details are withheld unless include_contact is set, and it enumerates the returned sub-resources. It also discloses the underlying POST /reporting/registrations/{id} read path, though it doesn't explain rate limits or error 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 dense sentences with the resource scope front-loaded and no padding; the trailing endpoint path is the only element of marginal value to an agent selecting the tool.

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 return-value burden and does so by naming the content groups returned. For a two-parameter read tool with full annotation coverage, nothing critical is missing, though expansion/format details of nested data are unstated.

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 include_contact property description already covers the default-off PII gating, so the sentence 'Contact details only with include_contact' largely repeats structured data. With the schema doing the heavy lifting, the 3 baseline 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 peer-to-peer registration in full') and enumerates the payload's contents (purchase history, team, totals, child registrations). The singular 'One... in full' implicitly separates it from sibling list tools like qgiv_list_registrations_by_date, though no sibling is named 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?

Usage is only implied: an agent can infer this fetches a single registration where the list tools return many, but the description never states when to prefer this over qgiv_list_recent_registrations or qgiv_list_registrations_by_date, nor any prerequisites. The include_contact note is a parameter rule, not a usage guideline.

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, idempotentHint, destructiveHint=false and openWorldHint, covering the safety profile. The description adds only the HTTP verb/path (POST /reporting/mappings/{id}), which is mildly useful context but does not disclose error behavior for a missing id or any auth/rate-limit nuance.

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?

Very short with no filler, and the purpose is front-loaded. However, the second fragment is a raw HTTP verb+path that adds little for an agent and reads as terse rather than purposeful.

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 rich annotations and no output schema, the essentials are present. It still omits what happens when the id does not exist or what the mapping object contains, leaving minor gaps for an agent.

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

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

Schema coverage is 100% and the single mapping_id parameter is documented in the schema as a numeric Qgiv id, so the schema carries the load. The description only echoes 'by id' without adding format, range, or lookup 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+resource ('One report mapping by id') and thus implicitly distinguishes itself from qgiv_list_report_mappings. It is clear but never names or contrasts the sibling 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?

No when-to-use guidance, no prerequisites, no named alternative. The 'one ... by id' phrasing hints at single-record retrieval versus the list tool, but the agent must infer this rather than being told.

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/safe, so the bar is lower, and the description still adds real behavioral value: a pagination cap ('first 100 shown'), a data-scoping note ('donor names only'), and the underlying HTTP method and path (POST /reporting/statements/{id}). These are traits an agent cannot get from the annotations alone.

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 dense sentence plus a path token; the record scope, payload, limit and redaction are all front-loaded with no filler. 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 no output schema, the description accepts the burden of describing returns and does so concisely (rows, 100 cap, donor names only). It could note what happens beyond 100 rows or how to paginate, which is the only 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 coverage is 100% and the single statement_id parameter is fully described in the schema, so the baseline of 3 applies. The description's 'by id' adds no syntax or format detail beyond what the schema already supplies.

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 scoped to a single record ('One statement by id'), which cleanly separates it from the sibling qgiv_list_statements. It also previews the payload ('with its transaction rows'). It stops short of naming the alternative explicitly, so not 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 'by id' scoping implies this is the single-record fetch versus the list/latest siblings, but there is no explicit when-to-use or when-not-to-use guidance. 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description's real value-adds are the privacy behaviors: contact details are gated behind include_contact, and card data is deliberately reduced to the last four digits. It also discloses that the read is performed via POST /reporting/transactions/{id}, a non-obvious detail for a read-only tool. A bit more on rate limits or pagination would push this higher.

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 dense, front-loaded sentence that names the payload first, then the two behavioral caveats, then the endpoint path. Every clause earns its place; the only minor cost is the somewhat breathless field list.

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 does the compensatory work by enumerating the returned sections and the contact/card masking rules. Combined with the endpoint disclosure, an agent has enough to call it correctly, though nothing says what an unknown id or empty result looks like.

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 meaning beyond the schema: it explains what include_contact actually unlocks (contact details) and what is returned without it, plus the card-number truncation behavior tied to the response rather than the flag itself.

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 precise verb+resource (fetch one transaction by id) and enumerates the payload scope: donation lines, fund/restriction, dedication, custom-field answers, event packages, registrations, refunds. The singular 'one transaction' clearly separates it from the many list_* siblings such as qgiv_list_recent_transactions and qgiv_list_transactions_by_date.

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: the singular 'one transaction' plus the required id suggests fetch-by-known-id versus the list siblings, but no alternative tool is named and no 'use this when...' condition is given. Adequate but leaves the routing decision 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the underlying POST /customFields/list endpoint and the shape of returned fields, but says nothing about pagination behavior or whether results are scoped per form.

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 tight sentence plus an endpoint, front-loaded with the resource and field list. Every fragment earns its place, though the field enumeration slightly crowds out other potentially useful context.

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

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

With no output schema, the description usefully enumerates the returned fields, and the schema covers paging. The only soft spot is the phrase 'configured on the form(s)' while the tool exposes no form-scoping parameter, leaving the result scope ambiguous.

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 limit and offset are fully documented (including the next_offset paging tip) in the schema itself. The description adds no parameter-level meaning, which is the baseline-3 case.

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 ('Custom (additional-question) fields configured on the form(s)') and enumerates the returned attributes. Siblings are all unrelated resources (transactions, pledges, events), so differentiation is implicit rather than explicit, which keeps this 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?

No statement of when to use this tool versus alternatives, no prerequisites, and no mention of how it relates to sibling list tools. The reader must infer that it is the only custom-field lister.

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/open-world, so safety is covered. The description adds genuinely useful context beyond that: the token-scoped visibility boundary, an explicit exclusion ('notification e-mail addresses are never returned'), and the transport detail (POST /events/list) which is unusual for a read and worth flagging.

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 resource and scope, no filler. The telegraphic field list ('id, dates and the top-level settings') is dense but readable; nothing is redundant 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?

There is no output schema, so the description correctly carries the return-shape burden and even discloses an excluded field. Pagination is covered by the schema, so the only remaining gap is that it does not characterize result size or ordering.

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 does add a small amount of meaning for include_details by enumerating packages/questions/promo codes, but it says nothing about limit/offset behavior beyond what the schema and its next_offset hint already provide.

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 resource (events, explicitly ticketed/auction events), the scope (forms the token covers), and the shape of what comes back (id, dates, top-level settings). The mention of top-level vs nested settings implicitly separates it from the get_* siblings that fetch a single registration/transaction.

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

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

It gives one concrete usage cue ('Set include_details for packages, questions and promo codes'), which tells the agent when to expand the payload. But it never says when to prefer this tool over list_registrations_by_date or get_registration, so routing among siblings is left 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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the notable fact that reads go through POST /pledges/list, which is useful behavioral context, but discloses nothing about pagination limits or result shape.

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 zero filler; the disambiguation from pledge records is front-loaded and the endpoint is noted compactly at the end. Nothing could be removed without losing signal.

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, and the description compensates by listing the fields returned, which is exactly what an agent needs here. It is slightly thin on whether results are scoped to one form or all forms, which matters for a form-configuration listing endpoint.

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 (limit, offset) are fully documented in the schema, so the description need not carry parameter meaning. The field list it gives (title, value, frequency, etc.) describes return content rather than parameters, so it adds little to parameter semantics.

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

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

The description names a specific resource (pledge options configured on form(s)), enumerates the configured fields, and explicitly distinguishes it from donor pledge records, which is the closest sibling (qgiv_get_pledge). An agent can tell what it returns 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?

The negative clause 'not donors' pledge records' excludes the adjacent use case and implicitly routes to qgiv_get_pledge, but no alternative is named explicitly and no when-to-use condition (e.g., setting up a form vs. reconciling donations) is 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so '(read-only)' adds nothing new. The description does contribute useful context by disclosing the underlying POST /reporting/refunds/last/{limit} endpoint, which is non-obvious for a read operation.

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 clause lists the return fields, followed by the endpoint. No filler; arguably the raw endpoint path is the least valuable part, keeping it just under 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?

Although there is no output schema, the description enumerates the returned fields, which compensates well; annotations cover the safety profile and the schema covers both parameters. Only ordering/pagination behavior for 'most recent' 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 both limit and include_contact are already well documented in the schema. The description only echoes limit via the endpoint template and says nothing about include_contact, so it adds no meaning beyond structured data.

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 recent refunds') and enumerates the returned fields, so the agent knows exactly what it gets. It does not distinguish itself from close siblings like qgiv_list_refunds_by_date, so it falls short of a 5.

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

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

There is no explicit guidance on when to use this versus qgiv_list_refunds_by_date or qgiv_get_refund. 'Most recent' implies a recency-based listing, but the agent must infer whether date-range or single-refund retrieval is preferable.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful context the annotations lack — the exact returned field set and that contact data is withheld unless include_contact is set — but says nothing about ordering guarantees, pagination, or limits beyond the schema's own bound.

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 purpose and returned fields, with the parameter caveat and endpoint placed after. The raw endpoint string is marginal value for an agent that calls the tool rather than the HTTP API, 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?

With no output schema and only two optional parameters, the description carries the return-value burden well by enumerating fields and the contact-gating rule. What is missing (order of 'most recent', default recency window, pagination) is minor given the low complexity.

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

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

Schema description coverage is 100%, so both parameters are already documented; the baseline is 3. The description reinforces include_contact's gating behavior and reveals that limit is a path segment on the endpoint, but adds no semantics the schema does not already carry.

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 — 'The most recent peer-to-peer (Hobnob) event registrations' — and enumerates the returned fields. It implicitly contrasts 'most recent' with the date-scoped sibling qgiv_list_registrations_by_date and the single-record qgiv_get_registration, but does not name any sibling 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?

Usage is only implied: 'most recent' suggests this is for the latest activity as opposed to a date-range query, and 'Contact details only with include_contact' hints at when to flip that flag. There is no explicit when-to-use/when-not statement and no alternative tool named.

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, so the bar is lower, and the description still adds real value: it discloses the privacy behavior that full card numbers are never returned and that donor contact data is suppressed unless include_contact is set, plus the newest-first ordering. It does not cover pagination or result-size behavior, but for a read-only list tool this is solid extra context.

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 dense sentence that front-loads the resource and ordering, followed by the endpoint path. The enumerated field list is long but earns its place because there is no output schema; 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 enumerating the returned fields, and it flags the key privacy constraints. The remaining gap is that it does not state what an empty or limit-capped result looks like, but an agent has enough to call it correctly.

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 both parameters are self-documented (limit range/default, include_contact off-by-default), so the baseline is 3. The description goes further by tying include_contact to concrete returned fields ('donor contact details are left out unless include_contact is set'), which clarifies the parameter's practical consequence rather than restating it.

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+resource ('most recent donations/transactions') and states ordering ('newest first as Qgiv returns them'), which implicitly separates it from the date-range and after-id siblings. It stops short of naming an alternative explicitly, so it is clear but not fully differentiated from the other recent/list 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?

Use is implied by 'most recent' plus the limit-bounded endpoint, giving the agent a reasonable sense of when this fits (no date filtering, just the latest N). However there is no explicit when-to-use statement and no guidance on choosing it over qgiv_list_transactions_by_date or qgiv_list_transactions_after_id.

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/no-destructive, so the safety profile is covered. The description adds real context beyond that: the exact return fields, the inclusion of a 12-month forecast, and the offset-style paging behavior, which the agent would otherwise not know.

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?

Dense but efficient: purpose, fields, filter, paging all front-loaded in a few clauses. The trailing endpoint hint ('POST /reporting/recurring/...') is the one element that may not earn its place for an agent, but it does not bloat the definition.

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

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

With no output schema, the description compensates by enumerating the returned fields and the forecast, and it covers filtering and pagination. An agent has enough to call it correctly, though it lacks any note on result ordering or large-result limits beyond the schema caps.

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 limit, offset, status and include_contact are already documented. The description only restates status filtering and offset/limit paging, adding no syntax or meaning beyond the schema. Baseline 3 for full schema coverage is appropriate.

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

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

States a specific verb and resource ('list recurring donation schedules') and enumerates the fields returned (id, dates, frequency, amount, state, donor, forecast). This clearly distinguishes it from the singular qgiv_get_recurring_schedule and from list_pledges.

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 status filter options and that paging uses offset/limit, which implies when the tool is useful (browsing schedules by state). However, it never names an alternative or states when to prefer this over qgiv_get_recurring_schedule or list_pledges, so usage is only implied.

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, so the bar is lower, and the description adds meaningful behavioral context: a hard 31-day window per call, offset/limit paging, and the actual POST endpoint. This tells the agent more than the annotations alone.

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 resource and scope, then the hard constraint and paging behavior, then the endpoint. Every clause earns its place with no redundancy.

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 still conveys the key operational facts an agent needs: date inclusivity, the 31-day ceiling, and offset/limit paging. It lacks any note on what the response contains or next_offset handling, but the schema covers the latter and overall it is 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 limit, offset, and the date fields are already documented in the schema. The description restates the paging mechanism and date inclusivity but adds no syntax or semantics beyond what the schema provides, 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 ('Refunds between two dates') with the key scoping constraint (inclusive, by date). It is clearly distinct from qgiv_get_refund and qgiv_list_recent_refunds by virtue of the date-range filter, 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?

The 31-day-per-call cap and paging hint imply usage context, but there is no explicit when-to-use guidance vs. qgiv_list_recent_refunds or qgiv_list_transactions_by_date. Usage is left to inference from the date-range framing.

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, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the hard 31-day window limit and the paging model, which are not visible in the schema or annotations. It doesn't describe rate limits or the per-record return shape, keeping it below a 5.

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

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

A single front-loaded sentence carries the scope, the constraint, the paging model, and the endpoint. The raw REST path (POST /reporting/registrations/dates/{begin}:{end}) is developer-oriented noise an agent cannot use, slightly diluting an otherwise tight statement.

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 should carry more of the return contract; it covers paging mechanics but says nothing about what a registration record contains or that include_contact changes the payload shape (that detail lives only in the schema). The 31-day cap and paging are covered, so it is minimally viable but not 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 limit/offset/end_date/begin_date/include_contact are already documented with defaults, bounds, and the next_offset paging tip. The description reinforces the range semantics but adds no parameter-level detail the schema lacks, so the baseline 3 applies.

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

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

The description states a specific verb and resource ("Peer-to-peer registrations between two dates") plus the scope (inclusive range, 31-day cap), which is enough to distinguish it from siblings like qgiv_list_recent_registrations. It stops short of naming that sibling explicitly, so the differentiation is implicit rather than stated.

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 supplies real operating guidance — the 31-day-per-call cap and offset/limit paging — which an agent needs before invoking. However, it never says when to pick this over qgiv_list_recent_registrations or qgiv_get_registration, so the choice among date-range vs. recent vs. single-record tools is left 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint). The description adds value beyond them by enumerating the fields each mapping record carries, which substitutes for the absent output schema, and by disclosing the underlying POST /reporting/mappings/list endpoint. It does not mention result volume or paging behavior beyond what the schema already documents.

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 resource and its returned fields. The trailing raw endpoint '/reporting/mappings/list' is low-value filler for an agent but costs little. No redundancy.

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-param, zero-required list tool, the description plus a full-coverage schema and safety annotations is mostly sufficient, and the field enumeration compensates for the missing output schema. The gap is routing: nothing tells the agent when to list mappings versus calling qgiv_get_report_mapping for a single one.

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 limit/offset are fully documented in the schema, so the description carries no additional parameter burden. Baseline 3 applies. The unexplained 'on the form(s)' scoping phrase adds slight ambiguity rather than clarity about inputs.

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?

Clear verb+resource: listing report (accounting export) mappings, with the parenthetical expanding the jargon. The returned fields are enumerated (id, identifier, mapping data, export service, type), which sharpens what a 'report mapping' is. It does not explicitly contrast itself with the sibling qgiv_get_report_mapping, though the list/get distinction is inferable.

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 statement of when to use this versus qgiv_get_report_mapping or when listing is preferable to fetching a single record. The phrase 'on the form(s)' suggests a form-scoping filter, but no such parameter exists in the schema, so this hints at context it never explains.

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 and open-world, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses the shape of the payload (summary totals only, no per-transaction rows), the paging mechanism, and the underlying endpoint POST /reporting/statements/list.

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 clauses, no filler, and the most decision-relevant information (what the rows contain and what to use instead for details) 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, the description compensates by enumerating the returned fields and clarifying the aggregation level. Paging is noted and the sibling for detail rows is named, leaving nothing an agent needs in order to call this tool correctly.

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 limit and offset are fully documented in the schema (ranges, defaults, next_offset guidance). The description restates 'paged with offset/limit' without adding syntax or semantics beyond what the schema provides, 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 statements) and immediately enumerates the returned fields (id, date, amount, fees, refunded, debited, credited, summary totals), which pins the resource down precisely. It also explicitly distinguishes itself from qgiv_get_statement by noting it excludes per-transaction rows.

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 routes the agent to qgiv_get_statement when per-transaction rows are needed, which is a genuine use/use-not distinction. It does not address the sibling qgiv_get_latest_statements, so the alternative mapping is incomplete.

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 and openWorld, so safety is covered. The description adds genuinely useful behaviour the annotations cannot: a guaranteed ascending sort order, limit-based paging, and the cursor-reuse contract (next_after_id used as after_id). It omits error/expiry behaviour of the cursor, 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 selection rule and ordering are front-loaded, and the endpoint is tucked at the end. It is a single dense sentence-chain; every clause carries information, though the pagination and cursor clauses could be split for readability.

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 still names the key return field (next_after_id) and its role, which is what an agent needs to paginate. The include_contact flag effect is only in the schema, but that is acceptable given full schema coverage.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining that next_after_id from a prior response should be fed back as after_id, and that paging is controlled by limit — adding value the per-field descriptions do 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?

The description states a precise verb and resource with scope: transactions with an id greater than the given one, ordered by id ascending. This distinguishes it cleanly from siblings like qgiv_list_transactions_by_date and qgiv_list_recent_transactions, which use different selection criteria.

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 context of use ('Handy for syncing new gifts') which implies the incremental-sync scenario versus date-window or recent-list siblings. It stops short of explicitly naming an alternative or a when-not-to-use condition, 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 read-only, idempotent, non-destructive behavior, and the description adds substantial operational detail beyond them: the 31-day window limit, the fact that Qgiv has no server-side paging so a busy range is fetched whole and sliced client-side, and the underlying POST endpoint. This warns the agent about cost/latency behavior that annotations cannot express.

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 dense sentences, each carrying distinct information: range semantics, paging mechanism, field parity with a sibling, and the no-server-side-paging caveat plus endpoint. Nothing is repeated and the scoping constraint 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, the description carries return-shape burden and partially does so by pointing to qgiv_list_recent_transactions for field parity. Combined with full schema coverage and rich annotations, the agent has enough to call it correctly; the only minor gap is that the actual response envelope is only implied, not described.

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, and the description adds the paging model (offset/limit slicing) and that bounds are inclusive. It does not explain include_contact or any date-format nuance beyond the schema, so it is a modest improvement rather than a full one.

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 (list), resource (transactions), and scope (between two dates, inclusive, max 31 days). It also differentiates itself from siblings by noting the same field set as qgiv_list_recent_transactions and by naming the date-range constraint, distinguishing it from qgiv_list_transactions_after_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?

Gives clear operational context: 31-day cap per call, and explicitly advises using a shorter range when a range is too large. It implies the alternative (qgiv_list_recent_transactions) via field parity but never states when to prefer that sibling over this one, so it stops short of full when/when-not routing.

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