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 that only public-facing data is returned, which is genuinely useful scope context, but it says nothing about auth requirements, error behavior on unknown slugs, or whether the enum-typed formType must match the slug's actual type.

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

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

A single front-loaded sentence with no filler; every item listed maps to actual return content. It is a fragment lacking a subject/verb, but that costs almost nothing in clarity.

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 enumeration of returned fields (title, dates, tiers, custom fields, state, URL) fills the main informational gap for a 3-parameter read tool whose annotations cover safety. Only the formType/slug relationship and failure modes remain 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%, including the orgSlug fallback to HELLOASSO_ORG_SLUG and the formType enum, so the schema does the heavy lifting. The description adds no parameter meaning beyond what structured fields already provide; baseline 3 applies.

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

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

The description names the specific resource and scope ('Public details of one form') and lists the concrete content returned (title, dates, tiers/prices, custom fields, state, URL), so an agent can distinguish it from list_forms or get_form_stats. The phrasing is a noun fragment rather than an explicit verb, but the intent is unambiguous.

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

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

'one form' implies use when you already have a single form in hand, versus the sibling list_forms, but no explicit when-to-use or when-not-to-use guidance is given. Nothing tells the agent why it would pick this over get_form_stats or how the two relate.

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 shape of the returned metrics, but says nothing about aggregation window (lifetime vs. date-bounded), freshness/caching, or auth/scope requirements. With annotations doing the heavy lifting, this is a modest but real contribution.

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

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

A single front-loaded sentence with no filler, and the key output examples appear first. The trailing ellipsis slightly weakens precision 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?

With no output schema, the description must convey return values, and it only sketches them ('amounts collected, number of orders/items...'). For a read-only stats endpoint that is roughly adequate, but the agent cannot tell whether results are totals over the form's lifetime, whether they include only paid orders, or what currency/format the amounts take.

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

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

Schema description coverage is 100%, including a documented enum for formType and the HELLOASSO_ORG_SLUG fallback for orgSlug, so the schema carries parameter meaning. The description adds nothing about parameters; 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 pair (statistics of one form) and parenthetically enumerates what the stats contain (amounts collected, order/item counts), which separates it from helloasso_get_form. It stops short of explicitly contrasting with that sibling, but the intent is unambiguous.

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

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

There is no statement of when to choose this over helloasso_get_form or helloasso_list_orders, and no note on required prerequisites such as a valid orgSlug default. Usage is only inferable from the name and the word 'statistics'.

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 behavior, so the safety profile is fully covered. The description adds only that custom fields are included, which largely restates the withDetails parameter rather than disclosing anything new (no error behavior for unknown ids, no note on what happens when custom fields are absent).

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 compact sentence with the resource and the id-based scoping front-loaded; nothing is wasted or buried.

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

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

For a simple two-parameter read tool with full annotations and complete schema coverage, the description is sufficient: it says what is fetched and that custom fields are included. Minor gap is the lack of any indication of failure mode for a nonexistent or inaccessible item id.

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 itemId and withDetails are already documented in the schema, including the default of true. The description's mention of 'custom fields' loosely maps to withDetails but adds no syntax, format, or edge-case meaning 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?

The description uses a clear verb ('Get') and resource ('item'), and disambiguates what an item can be (membership, ticket, donation). It implicitly separates itself from helloasso_list_items by saying 'by id', but never names a 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: the 'by id' phrasing signals single-record retrieval as opposed to listing. There is no statement of when to prefer this over helloasso_list_items or how it relates to helloasso_get_order / helloasso_get_payment for the same underlying data.

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 behavior, so the safety profile needs no restating. The description adds useful context by naming the returned sections (payer, items, payments, amounts), but says nothing about failure modes for unknown ids, permission requirements, or the effect of the withFormData flag.

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 with zero filler; the payload enumeration is packed into the same sentence. Nothing is wasted or buried.

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

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

With no output schema, the description usefully names what the response contains, which is the most valuable thing it can do here. The remaining gap is the withFormData option, which is unexplained in both description and (beyond one line) schema, but for a 2-parameter read tool this is close to 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 coverage is 100%: orderId is documented as "Order id" and withFormData as "Include form data." The description's "by id" reinforces orderId but adds no meaning beyond the schema and is silent on withFormData. Baseline 3 applies when the schema carries the parameter detail.

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?

"Detailed order by id" states a specific verb (retrieve) and resource (order) plus the lookup key, and enumerates the payload (payer, items, payments, amounts). This distinguishes it from list_orders, though it does not name 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 phrase "by id" implies usage when a specific order identifier is already known, versus the list tool for discovery. However, no explicit when-to-use or when-not-to-use guidance is given, so the routing to list_orders vs get_order 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, idempotentHint and openWorldHint, so the safety profile is covered. The description adds that only *public* details are exposed, which is meaningful context, but says nothing about auth requirements, error behavior for unknown slugs, or default-slug resolution.

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 short sentence, front-loaded with the resource and immediately followed by the returned field categories. No waste, though it is a fragment rather than a full directive sentence.

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

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

With no output schema, the description usefully enumerates what fields come back, and the single parameter is fully documented in the schema. What remains missing (auth, error cases) is minor for a simple public read.

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 orgSlug parameter has 100% schema coverage, including the helloasso.com/associations/<slug> format and the HELLOASSO_ORG_SLUG default. The description adds nothing 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?

Names the resource (HelloAsso organization) and the returned content (name, description, address, logo, URLs), with 'get' implied by the title. It is reasonably distinguishable from helloasso_list_my_organizations because it fetches one org's details, though the description never explicitly contrasts the two.

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

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

Usage is only implied: an agent infers you call this to fetch a single org's profile. There is no statement of when to prefer it over helloasso_list_my_organizations, nor any prerequisite such as needing a slug.

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 and non-destructive, so safety is covered. The description adds genuine value by enumerating the returned data (amount, state, payer, order, refund operations), which compensates for the absent output schema.

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

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

A single compact sentence with the key information (id-based lookup plus returned fields) front-loaded. Nothing is wasted.

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

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

For a simple one-parameter read tool with no output schema, the description covers both the lookup key and the shape of the response. Only minor gaps remain, such as error behavior for an unknown id.

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 paymentId parameter is fully documented in the schema. The description adds nothing beyond 'by id', so the baseline 3 is appropriate.

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

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

The description names a specific verb and resource ('Detailed payment by id') and previews the payload ('amount, state, payer, order, refund operations'). It implicitly distinguishes itself from helloasso_list_payments by requiring an id, though it never names 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?

Usage is only implied: 'by id' signals you need a payment identifier, which suggests fetching detail for a known payment rather than browsing. There is no explicit when-to-use versus helloasso_list_payments or helloasso_get_order, and no prerequisites 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, non-destructive and openWorld, so the safety profile is covered. The description adds one genuine behavioral fact not in annotations — results are ordered newest first — plus pagination, which is largely restated by the continuationToken/pageIndex schema fields. No return shape, page-size defaults, or auth/scope notes beyond 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?

Two short sentences, no filler, with the resource identity front-loaded and the ordering/pagination note trailing. 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?

For a read-only, zero-required-parameter list tool with full schema coverage and no output schema, the description covers what the resource is and how results are ordered. It could say more about default org resolution or what a form record contains, but nothing essential for a correct call is missing.

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

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

Schema description coverage is 100%, so all six parameters (states, formTypes, orgSlug, pageSize, pageIndex, continuationToken) are already documented, including enum values and the continuationToken preference guidance. The description only loosely echoes the filterable dimensions via its type list, 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 ('List') and resource ('organization forms (campaigns)') and enumerates the concrete form categories, which maps directly to the formTypes enum. It is clearly distinct from singleton siblings like helloasso_get_form or the type-metadata sibling helloasso_list_form_types, though it never names those alternatives 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 description implies the browsing/listing use case ('Newest first, paginated'), but gives no explicit when-to-use, when-not-to-use, or named alternative (e.g. use helloasso_get_form when you already have a form slug). 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?

The annotations already declare readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is covered. The description adds one genuinely non-obvious behavioral fact: only types with at least one existing form are returned, which prevents the agent from assuming an exhaustive type catalog. It stops there, saying nothing about the shape or size of results or how the states filter intersects with that scoping.

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 with no filler, and the scoping qualifier is placed where it reads first. It is a fragment rather than a full sentence, which costs it a point against the cleanest possible phrasing.

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

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

With only two optional parameters and rich annotations, the definition is nearly sufficient, and the phrase 'form types' partially substitutes for the absent output schema. However, with no output schema the description could say what a returned type entry looks like, and it never mentions the orgSlug default or empty-result behavior.

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

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

Schema description coverage is 100%, including the HELLOASSO_ORG_SLUG default, so the schema carries the parameter burden. The description adds no meaning about the states filter or whether it narrows the 'has at least one form' scoping, 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?

Names the resource precisely ('Form (campaign) types') and clarifies what a form type means here, which separates it from the sibling helloasso_list_forms that returns forms rather than types. The verb is only implied by the title rather than stated in the description, keeping it just short of a 5.

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

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

The sentence describes what is returned, not when to call it. There is no mention of choosing this over helloasso_list_forms, no prerequisites, and no note about what happens when no forms exist. An agent must infer the use case entirely.

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 fully covered by structured data. The description contributes the fact that results carry custom field answers, but says nothing about result volume, pagination behavior, or rate limits beyond what parameters imply.

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 verb and resource, then the scoping rule, then illustrative examples. No filler. It is slightly packed but every clause carries information an agent can use.

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 15-parameter, no-output-schema listing tool, the description is adequate: scope, examples, and custom-field inclusion are covered. It omits what an item record contains and how this differs from orders/payments, which matters given several similarly shaped sibling list tools.

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% across all 15 parameters, so the schema already documents date ranges, enum values, pagination, and the formType/formSlug pairing. The description only reinforces the formType + formSlug combination and the presence of custom fields; it adds no syntax or filtering semantics beyond the schema.

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

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

States a specific verb (list) and resource (items) and clarifies the two scopes: whole organization vs a single form identified by formType + formSlug. The examples (members of a membership campaign, participants of an event) make 'item' concrete. It does not explicitly contrast with siblings like helloasso_list_orders or helloasso_get_item, so an agent must infer that boundary.

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

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

The conditional phrasing 'by the organization or by one form (formType + formSlug)' implies how to scope the query, which is genuine usage guidance. However, there is no explicit when-not statement, no mention of when to prefer list_orders/list_payments, and no guidance on when to use helloasso_get_item for a single record.

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 fully covered. The description adds one genuinely useful behavioral fact beyond them: results are limited to organizations the API client has rights on, so an empty or partial list is expected rather than an error. Nothing is said about pagination or ordering.

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 short, front-loaded sentence with no filler, but it is a noun phrase fragment rather than a complete statement of action, which leaves the 'list' semantics slightly implicit.

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 zero parameters, rich annotations, and no output schema, the description covers what the tool returns (accessible organizations) and why an agent would call it (to obtain an organization slug). The only gap is return shape or count, which an agent could infer but must verify at call time.

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 per the baseline this is a 4. There is no parameter semantics to explain and the description does not need to.

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 the resource and its scope precisely: organizations the authenticated API client has rights on. It implicitly distinguishes itself from the singular sibling helloasso_get_organization, though it never uses an explicit verb and leans on the name/title to convey the listing action.

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

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

The parenthetical 'useful to find the organization slug' gives a concrete motivating use case, which is real guidance for routing. However, it does not say when to use this versus helloasso_get_organization, nor does it state any prerequisites or exclusions.

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 safety behavior is fully covered. The description adds only a bare mention of date range, search and pagination, without disclosing default page size, result shape, or how results are ordered beyond the schema's per-field defaults.

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

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

Two short sentences with the scope constraint front-loaded and zero filler; nothing to trim.

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

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

With 12 optional parameters, no output schema and no required fields, the schema carries most of the load and does it well. The description still omits how pagination should be driven across pages and roughly what the response contains, which an agent listing large order sets would want.

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

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

Schema description coverage is 100%, including the formType/formSlug pairing, ISO 8601 patterns, default org slug and the continuationToken hint, so the baseline is 3. The description restates the form-scoping rule and the filter families but contributes no semantics the schema lacks.

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 orders') plus the two scopes (organization-wide vs. single form gated on formType + formSlug). It does not distinguish itself from lookalike siblings such as helloasso_list_payments or helloasso_list_items, so an agent must infer the boundary.

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

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

The description gives an implicit usage rule — supply formType + formSlug to narrow to one form — but never states when to use this instead of helloasso_get_order for a single record, nor which of pageIndex vs. continuationToken to prefer. 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, idempotentHint and non-destructive, so the safety profile is covered. Everything the description mentions (date range, states, search, sorting, pagination) is restated from the schema; it adds nothing about result volume when unscoped, rate limits, or whether continuationToken supersedes pageIndex.

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, and the primary scope rule is front-loaded before the capability summary. Nothing is repeated and nothing needs trimming.

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 12-parameter, all-optional list tool with a fully documented schema and annotations carrying the safety profile, the description covers scope and the main filter families adequately. It stops just short of guiding the agent on pagination strategy or the cost of an unscoped org-wide query, which are the remaining items an agent would want.

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

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

Schema description coverage is 100%, including enum members and defaults for pageSize, sortField, sortOrder and the orgSlug environment fallback, so the baseline of 3 applies. The description only lists parameter families at a level the schema already exceeds (e.g. the formType+formSlug pairing rule is stated in both schema fields).

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 payments') and adds real scope: org-wide by default, narrowed to a single form when formType + formSlug are supplied. The list-vs-get distinction against sibling helloasso_get_payment is self-evident from the verb, so it doesn't need to name the sibling explicitly — hence 4 rather than 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 one conditional rule ('or of one form when formType + formSlug are given') is genuine usage guidance, but the rest ('Supports date range, payment states, search, sorting and pagination') is a capability list, not when-to-use guidance. There is no statement of when not to use it or when to prefer helloasso_get_payment or helloasso_list_orders instead.

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