Raisely MCP by usefulapi

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

Annotations only supply destructiveHint=true, so the description does real work: it names the underlying endpoint (POST /donations), discloses the { data: {...} } body wrapping requirement, explains that `fields` is merged OVER the typed parameters, and states the return value. Given the destructiveHint, it could say more about side effects or failure behavior, but it adds meaningful context beyond the annotation.

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

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

Front-loads the mutation warning and the offline-only use case, then moves to API mechanics. Dense but nearly every sentence carries information; only the enumeration of optional example fields (firstName, lastName, message, ...) is mildly 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?

Covers the pieces an agent needs for a 10-parameter, nested-object write tool: endpoint, body envelope, required fields, the flexible `fields` bag, and the return value. There is no output schema, and the description compensates by saying it returns the created donation; error and idempotency behavior remain unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by restating which fields the API strictly requires (amount, currency, email, type, method), by spelling out that amount is in cents/smallest currency unit, and by explaining the `fields` escape hatch for everything else. The merge-precedence detail is the most valuable addition for an agent filling this payload.

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

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

Opens with 'MUTATES Raisely data: records a donation' — a specific verb plus resource — and immediately narrows scope to offline/manual donations like cash or cheque. That is enough to separate it from every read-oriented sibling (raisely_get_donation, raisely_list_donations) and from raisely_update_profile.

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 names the use case ('use for OFFLINE/manual donations — e.g. cash or cheque'), which is the key routing signal versus online donation flows. It stops short of stating when not to use it (e.g. that online/gateway payments should not be created this way), so it is strong but not complete.

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 destructiveHint annotation already signals mutation; the description reinforces this with 'MUTATES Raisely data' and adds useful API-level context: POST /posts, the `{ data: {...} }` wrapping, required API fields, and the created-post return. It does not cover auth or rate-limit behavior, so it stops short of a 5.

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

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

The description is front-loaded with the mutation warning and API endpoint, then moves efficiently through required fields, linking, extra fields, and return value. Every sentence carries operational information and there is no filler.

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

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

For a create tool with no output schema, nested `fields`, and five parameters, the description is complete enough to call correctly: it covers endpoint, body wrapping, required API fields, profile linking, extras, and return value. The annotation also covers the destructive safety signal.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: `profileUuid` is passed through `fields`, extra fields like `date` go via `fields`, and `photoUrl` is called out as API-required even though the schema only marks path/body as required.

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: 'publishes a post (a campaign/profile update)' and identifies the API endpoint POST /posts. This clearly distinguishes it from sibling read/list tools such as raisely_list_posts and raisely_get_campaign.

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 makes clear that this is the create/publish path and names the API-required fields and how to link a profile through `fields`. It does not explicitly state when not to use it or name alternatives, but the create context is unambiguous among siblings.

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, so the safety profile is covered. The description adds real behavioral context beyond that: this call doubles as a credential verification step tied to RAISELY_API_KEY, and it discloses the response envelope { data:{...} }. It does not say what happens on an invalid key, which is the main remaining gap.

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

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

Three short sentences with the purpose, usage directive, endpoint, and return shape, all front-loaded with no filler. Every sentence adds information an agent would otherwise have to guess.

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

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

For a zero-parameter, read-only authentication check with no output schema, the description supplies enough to invoke it correctly: what it returns, what it verifies, and the endpoint. The return shape is only sketched as { data:{...} }, so the exact fields and privileges format remain opaque.

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 the schema fully carries the (empty) parameter burden and the description has nothing to compensate for. The credential dependency on RAISELY_API_KEY is noted, which is the only parameter-like input.

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

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

States a specific verb and resource ('show the currently authenticated user plus their privileges') and names the underlying endpoint GET /authenticate. This clearly separates it from the sibling raisely_get_user, which retrieves an arbitrary user rather than the caller's own identity.

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 directs the agent to 'Use this first to confirm RAISELY_API_KEY works,' which is actionable sequencing guidance tied to credential validation. It stops short of naming alternatives (e.g. raisely_request) or stating when not to use it, but the intended context is unambiguous.

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, so the safety profile is covered. The description adds value beyond that by naming the underlying endpoint (GET /campaigns/{campaign}) and the response envelope ({ data:{...} }), but says nothing about error behavior, missing-campaign handling, or auth requirements.

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

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

Three short sentences, each earning its place: purpose, endpoint mapping, and response shape. Front-loaded with the core action and free of 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 carries some burden for returns — it gives the { data:{...} } envelope, which is enough shape for a simple getter. Minor gaps remain around failure cases, but for a one-parameter read tool this is nearly 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% and the single parameter is fully documented in the schema ('The campaign uuid or URL path/slug'). The description restates the same accepted forms without adding format examples or constraints, 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?

States a specific verb and resource ('Fetch a single campaign') and the lookup key ('by id or path/slug'). The word 'single' implicitly distinguishes it from the raisely_list_campaigns sibling, 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 implied by the tool's nature – an agent can infer this is for retrieving one campaign when the id/slug is known. However, there is no explicit when-to-use guidance, no mention of when to prefer raisely_list_campaigns or raisely_request, and no prerequisites or error conditions described.

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, so the safety profile is covered. The description adds genuine value beyond that by disclosing the underlying endpoint (GET /donations/{uuid}) and the response envelope shape ({ data:{...} }), which matters because there is no output schema.

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

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

Three short, front-loaded sentences with no filler: purpose, endpoint mapping, return shape. Every sentence carries distinct 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 simple single-record read with one fully-documented parameter and a readOnly annotation, this covers purpose, endpoint, and return envelope. It omits error behavior (e.g., what happens when the uuid is not found), which is a minor remaining gap.

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

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

Schema description coverage is 100% — the uuid parameter is documented as 'The donation uuid.' The description only restates 'by uuid', adding no format, sourcing, or lookup guidance, so the baseline 3 for a fully-documented single parameter is correct.

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 ('Fetch') and resource ('a single donation by uuid'), and the word 'single' implicitly separates it from the list_donations/list_user_donations siblings. It stops short of naming the alternative it is not, so it is clear but not fully differentiated.

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: use this when you already have a donation uuid and need exactly one record. There is no explicit when-to-use/when-not guidance and no pointer to the sibling tools (raisely_list_donations, raisely_list_user_donations) that cover the bulk-retrieval case.

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 readOnlyHint annotation already establishes that this is a safe read. The description adds genuinely useful context beyond that: the underlying endpoint (GET /profiles/{path}) and the fact that the path accepts either a slug or a uuid as a string, which tells the agent both identifier forms are valid. It stops short of describing not-found or auth behavior, keeping it out of the top score.

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: purpose, identifier semantics, endpoint, and return envelope. The key information (slug-or-uuid) is front-loaded and nothing is padding.

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

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

For a one-parameter read tool with no output schema, the description supplies the endpoint and the return envelope shape ({ data:{...} }), which is exactly the missing piece. It does not cover failure modes such as an unknown path, but the core call path is 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% and the single 'path' parameter is already documented in the schema. The description's clarification that it is 'a string either way' reinforces but does not extend the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a single fundraising profile'), and the word 'single' implicitly distinguishes it from the raisely_list_profiles sibling. It does not name that sibling explicitly, so an agent must infer the list-vs-single split, but the purpose itself is unambiguous.

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

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

Usage is only implied: you call it when you have a profile path or uuid and want one record. There is no statement of when to prefer this over raisely_list_profiles or raisely_request, and no mention of prerequisites or error conditions.

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 readOnlyHint annotation already establishes that this is a safe read. The description adds the underlying API endpoint and the response envelope shape, which is useful, but it does not cover error behavior such as an unknown uuid or any rate-limit or permission 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?

Three short, front-loaded sentences. The purpose comes first, followed by the endpoint and return shape, with no padding or repetition.

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 annotations and full schema coverage, the description supplies the endpoint and return envelope, leaving little ambiguity. It is close to complete, with only minor gaps around failure modes.

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

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

Schema description coverage is 100%, and the single uuid parameter is fully documented in the schema. The description only restates that lookup is by uuid and adds no format, source, or validation detail beyond the schema.

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

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

The description states a specific verb and resource: fetch a single subscription by uuid, and clarifies that a subscription is a recurring donation. It implicitly contrasts with the sibling list_subscriptions tool by emphasizing 'single' and uuid lookup, though it does not name the alternative.

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: call this when you have a subscription uuid and need that one record. There is no explicit guidance on when to use it instead of raisely_list_subscriptions or other get/list siblings, and no mention of 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?

readOnlyHint already declares this is a safe read operation, and the description adds the API endpoint and return wrapper shape. It omits auth requirements, not-found behavior, and rate limits, which would add richer behavioral 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?

Three short sentences with the core operation front-loaded and no wasted text. The endpoint and return shape are useful supplements, not padding.

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

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

For a simple single-resource read tool, this is nearly complete: identifier, endpoint, and return wrapper are covered, and annotations handle safety. Error/not-found behavior is the main omission.

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

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

Schema coverage is 100%, so the single uuid parameter is already documented. The description restates that lookup is by uuid but adds no format or validation details 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 and resource: fetch a single user by uuid, and clarifies donor/supporter meaning. It does not explicitly differentiate from get_authenticated_user or list_users, so it stops short of full sibling distinction.

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

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

Usage is implied by 'by uuid' for a single-user lookup, but the description does not state when to use this instead of get_authenticated_user or list_users. No exclusions or alternatives are provided.

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 readOnlyHint annotation already declares the safe read behavior, and the description adds useful context beyond that: the exact API path and the return shape `{ data:[...], pagination }`. It does not cover auth, rate limits, or edge cases, but for a simple read wrapper it provides solid behavioral 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?

Three short sentences, front-loaded with the purpose, followed by the endpoint and return shape. There is no wasted text.

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

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

For a simple campaign-scoped read endpoint with full schema coverage and a readOnly annotation, the description supplies the key missing behavioral facts: the API route and the response envelope. An agent has enough information to select and invoke 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 description coverage is 100%, so parameters such as limit, offset, campaign, and the verbatim params bag are fully documented in the schema. The description adds no parameter-level detail beyond the endpoint path, so 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?

States a specific verb and resource (list donations) scoped to a specific campaign, and names the underlying API endpoint. That scope clearly distinguishes it from the broader donation-listing siblings without requiring schema inspection.

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 'for a specific campaign' implies when to use it, but the description does not explicitly say when to prefer this over raisely_list_donations or raisely_list_user_donations. Usage is reasonably inferable but not guided.

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, so safety is covered; the description adds real value by mapping to the underlying API call (GET /campaigns/{campaign}/profiles) and disclosing the response envelope (data plus pagination), which matters given there is no output schema. It stops short of noting rate limits, default page size behavior, or what the pagination object contains beyond its presence.

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 with zero filler: purpose, endpoint mapping, and return shape, with the scoping constraint front-loaded. Nothing could be removed without losing 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, disclosing the { data, pagination } envelope is exactly what an agent needs to consume results, and pagination parameters are covered by the schema. Minor gaps remain around how this differs operationally from raisely_list_profiles and whether the nested 'params' filters interact with the typed limit/offset.

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

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

Schema description coverage is 100%, so all four parameters (limit, offset, params, campaign) are already documented in the schema, including the escape-hatch 'params' object. The description adds no parameter-level detail beyond implying the campaign is a path identifier; 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 fundraising profiles') plus the scoping constraint ('for a specific campaign'), which implicitly separates it from the sibling raisely_list_profiles. It does not name that sibling explicitly, so the differentiation relies on the reader inferring that the unscoped tool exists.

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 leading 'Convenience:' signals this is a shortcut for the campaign-scoped case, implying you should use it when you already know the campaign. However, it never states when to prefer raisely_list_profiles or raisely_request instead, nor any prerequisites such as needing a campaign uuid first.

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, so safety is covered. The description usefully adds the backing endpoint and, importantly, the return envelope shape { data:[...], pagination }, which is real value since there is no output schema. It says nothing about rate limits, default paging behavior, or filtering semantics beyond what the schema carries.

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

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

Three compact sentences with zero filler, front-loaded with the core purpose and immediately followed by the endpoint and return shape. Every sentence 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?

Because there is no output schema, the description's disclosure of the { data, pagination } envelope is exactly the missing piece an agent needs. With annotations covering safety and the schema covering all three parameters, the definition is nearly complete, only lacking routing guidance versus siblings.

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% – limit, offset, and the free-form params object are all documented in the schema itself, including the verbatim pass-through behavior and example filters. The description adds no parameter meaning beyond that, 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?

States a specific verb+resource ('List fundraising campaigns') and pairs it with the underlying API operation (GET /campaigns), so the agent knows exactly what it does. It does not explicitly name or differentiate from the closest sibling raisely_get_campaign (single campaign), leaving the list-vs-get distinction to be inferred from the verb.

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

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

No guidance on when to choose this over raisely_get_campaign, raisely_request, or the more specific list tools like raisely_list_campaign_donations. Usage is only implied by the word 'List'; there are no conditions or exclusions stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds the HTTP endpoint and the return shape '{ data:[...], pagination }', which is valuable since no output schema exists. It omits auth requirements and rate-limit behavior, but the added return structure is real context beyond 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?

Three short sentences, front-loaded with the core action and free of filler. Slightly terse given the sibling ambiguity, but nothing is wasted.

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

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

For a read-only list tool with 100% param coverage, the description supplies endpoint mapping, filter mechanism, and return shape, which largely compensates for the missing output schema. The main remaining gap is disambiguation from the scoped donation-list siblings.

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

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

Schema description coverage is 100%, so the schema already documents limit, offset, and the free-form params object. The description restates the same filter examples (campaign, status, sort, order) already present in the schema's params property, adding no new syntax or semantics — baseline 3 applies.

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

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

States a specific verb+resource and maps it to the underlying API call (GET /donations), which is genuinely useful. However, it does not distinguish itself from siblings like raisely_list_campaign_donations or raisely_list_user_donations, so an agent cannot tell from the description whether this returns all donations or a scoped set.

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 or when-not-to-use guidance is given, and no alternative sibling (e.g. list_campaign_donations for a scoped query) is named. The filter examples hint at supported use but do not route the agent between the many list_* siblings.

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 annotation already declares readOnlyHint=true, so safety is covered. The description adds useful behavioral context beyond annotations: it identifies the underlying Raisely API endpoint (GET /orders) and the return envelope shape ({ data:[...], pagination }).

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 description is very concise and front-loaded: resource name, scope clarification, endpoint, filtering note, and return shape are all stated in a few efficient fragments with no wasted text.

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

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

For a read-only list tool with no output schema, the description supplies the endpoint and return envelope, and the input schema fully covers pagination and filtering parameters. It omits auth or rate-limit details, but those are minor for this tool's 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 the schema already documents limit, offset, and the params filter object thoroughly. The description only restates that filtering is done through `params`, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource ('List orders') and clarifies that orders are ticket/product purchases, which helps distinguish them from sibling donation tools. However, it does not explicitly contrast this tool with siblings such as raisely_list_donations or raisely_list_subscriptions.

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 says to filter via `params`, but that is invocation guidance rather than when-to-use guidance. It gives no explicit context for choosing this tool over sibling list tools or any 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=true, so the description needn't assert safety. It adds real value by disclosing the return envelope `{ data:[...], pagination }`, which matters because there is no output schema, and by naming the exact API path so behavior is predictable. It omits auth requirements and rate limits, keeping it short of a 5.

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

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

Four short clauses, front-loaded with the purpose, and nothing is padded. The parenthetical and endpoint reference each earn their space, though the telegraphic 'Filter via `params`' is borderline 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 a fully documented schema and no output schema, the description covers purpose, endpoint, filtering channel, and return shape — enough for correct invocation. It stops short of explaining pagination iteration (limit/offset loops) or auth expectations.

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 limit, offset, and the free-form `params` object all documented, so the schema carries the semantics. The description adds only 'Filter via `params`', which is essentially restatement; it does not enumerate supported filter keys or explain merge precedence beyond what the schema already says.

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

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

States a specific verb and resource ('List posts') and clarifies what a post is ('campaign/profile updates'), plus the underlying endpoint GET /posts. It is clearly the read counterpart to raisely_create_post, though it never names that 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 implied by the tool name and the note that filtering goes through `params`, but there is no explicit guidance on when to use this versus raisely_list_campaign_profiles or raisely_list_profiles, nor any prerequisite or exclusion. The agent must infer the selection criteria.

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

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

The readOnlyHint already establishes that this is a safe read operation. The description adds useful context by naming the endpoint and return shape, but it does not disclose authentication requirements, rate limits, or deeper pagination behavior beyond returning a pagination object.

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

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

Three compact sentences, front-loaded with the resource and purpose, followed by endpoint, filtering, and return shape. No sentence 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?

There is no output schema, and the description compensates by describing the return shape as `{ data:[...], pagination }`. The input schema is fully described, and the read-only annotation covers safety, though sibling differentiation remains a small 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 the schema already documents `limit`, `offset`, and `params`. The description repeats the filterable `params` idea with examples but adds little syntax or 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 states a specific verb and resource: list fundraising profiles, clarified as individual/team fundraising pages. It does not explicitly distinguish this tool from sibling tools such as raisely_list_campaign_profiles or raisely_get_profile.

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 filter examples via `params` (campaign, type, sort, order), which implies usage for querying profiles. However, it does not say when to use this general list tool versus the campaign-specific list tool or the single-profile getter.

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, so safety is covered. The description usefully adds the underlying endpoint and the response envelope (data + pagination), which is real behavioral context. It omits any auth/rate-limit or filter-behavior detail, so it is additive but not rich.

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, zero filler, with the core purpose front-loaded before endpoint and return shape. Every sentence carries distinct information.

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

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

With no output schema, the description compensates by stating the return envelope. All three parameters are documented in-schema, so the definition is sufficient to invoke correctly; only usage routing to alternatives is missing.

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

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

Schema description coverage is 100%, with limit, offset, and the free-form params object all documented in the schema. The description adds nothing about parameter meaning, which is acceptable given the schema does the heavy lifting.

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

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

States a specific verb and resource: "List saved audience segments," immediately distinguishing it from the get_*/create_* siblings. It doesn't explicitly name alternatives (e.g. raisely_request as a generic fallback), which keeps 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?

There is no guidance on when to use this versus raisely_request or other list tools, nor any prerequisites or exclusions. The listing intent is only implied by the verb "List."

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

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

Annotations already carry readOnlyHint=true, so safety is covered. The description adds real behavioral context beyond the annotations: the underlying API route (GET /subscriptions), the fact that filtering goes through `params`, and the return shape { data:[...], pagination }, which is valuable since there is no output schema.

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

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

Three short, front-loaded sentences with no filler. Purpose, endpoint, and return contract are delivered in order of importance, and every sentence earns its place.

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

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

For a read-only list tool with no output schema, the description supplies the endpoint, filter entry point, and return shape, which is most of what an agent needs. It slightly under-serves on guidance about pagination defaults and filter values, but the schema covers the numeric paging controls.

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 three parameters (limit, offset, params) are already well documented in the schema. The description only adds 'Filter via `params`', which restates schema content without adding syntax or accepted-filter detail, 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?

States a specific verb (List) and resource (subscriptions), and the parenthetical '(recurring donations)' clarifies the domain concept. It does not explicitly contrast with siblings like raisely_list_donations, but the resource distinction is clear enough for selection.

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 when-to-use or when-not-to-use guidance, and no routing to alternatives such as raisely_get_subscription for a single record or raisely_list_donations for one-off gifts. Usage is only implied by the tool name and the '(recurring donations)' aside.

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, so safety is covered; the description adds value by naming the REST endpoint and disclosing the return envelope ({ data, pagination }), which is meaningful since there is no output schema. It stops short of noting ordering or whether results are scoped to the authenticated user's organisation.

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 purpose, then endpoint, then return shape. Nothing redundant or padded.

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

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

For a read-only list tool with full schema coverage and readOnly annotations, the description covers purpose, endpoint and return envelope, compensating for the absent output schema. Minor gaps remain around result ordering and scope, which an agent might want before filtering.

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

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

Schema description coverage is 100%, with limit, offset and params fully documented in the schema itself. The description only alludes to pagination via the return shape and adds no syntax or semantics beyond the schema, 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+resource ('List tags') and clarifies what the resource is ('used to label records'), plus the underlying endpoint GET /tags. It doesn't explicitly differentiate from siblings like raisely_list_segments, but the resource noun is unambiguous against all listed siblings.

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

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

The description implies usage (fetch labels to apply to records) but gives no when-to-use vs alternatives, no note on when to page through results, and no exclusions. For a simple read-list tool this is minimally adequate.

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, so the safety profile is covered. The description adds useful context by disclosing the return envelope ({ data:[...], pagination }), which matters since there is no output schema. It does not cover failure behavior (e.g. unknown uuid) or whether results are ordered.

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 fragments with the purpose front-loaded and zero filler. The 'Convenience:' label is slightly cryptic but costs almost nothing, and no sentence 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 4-parameter tool with a nested free-form params object and no output schema, the description does cover the return envelope and the upstream mapping, which is the main missing piece. It remains thin on pagination semantics and on what the free-form params filters actually accept beyond the schema's examples.

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 uuid, limit, offset, and the params passthrough are already fully documented in the schema. The description adds no parameter-level detail (e.g. which filter keys are commonly useful), 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 a donor's giving history) and pins it to the concrete upstream endpoint GET /users/{uuid}/donations, so intent is unambiguous. It stops short of explicitly contrasting with siblings like raisely_list_donations or raisely_list_campaign_donations, leaving the scoping distinction to be inferred from the name.

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 'Convenience' hints this is a shortcut over a more general call, but no when-to-use or when-not-to-use guidance is given. An agent gets no signal on choosing this over raisely_list_donations, raisely_list_campaign_donations, or a raw raisely_request.

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, so the safety profile is covered. The description adds real value beyond that by disclosing the response shape ({ data, pagination }) and that `params` are sent verbatim, which helps the agent reason about output and filtering 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?

Three short sentences: identity, endpoint, filtering, and return shape, with the resource purpose front-loaded. Nothing is padded and 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, including the { data, pagination } return shape and the params-merge note is the right compensating detail for a 3-param list tool with a nested object argument. Only minor omissions (e.g. noting defaults or total-count semantics) remain.

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 params are already fully documented in the schema. The description only restates the params-filtering mechanism without adding syntax or semantics beyond it, so baseline 3 applies.

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

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

States a specific verb and resource ('List users') and clarifies what a user is (donors/supporters/fundraisers), plus the underlying Raisely endpoint. It implicitly distinguishes itself from the singular raisely_get_user, but never names siblings explicitly, so it stops short of a 5.

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

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

The only usage instruction is 'Filter via `params`', which is a how-to rather than a when-to-use. There is no guidance on choosing this over raisely_get_user (single lookup) or raisely_list_user_donations (scoped listing), leaving the agent to infer.

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; the description reinforces this with 'READ-ONLY — only GET is allowed' and adds that it returns parsed JSON. It does not cover auth requirements, error behavior for invalid paths, or pagination handling, so it is useful but not rich.

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 short clauses, front-loaded with the tool's role, then the hard constraint, then the path format, then the return. No filler sentences.

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 pass-through with no output schema, the description covers purpose, constraint, input format, and a brief return statement. Auth requirements and error semantics are the only meaningful omissions.

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

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

Schema description coverage is 100% and the schema already gives the exact format plus a '/donations?limit=50' example, so the description mostly restates it. The added {uuid} path example and the emphasis that the query string must be included in the path are minor value-adds over 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 (GET), resource (any Raisely API path), and explicitly scopes itself as the escape hatch for paths 'not wrapped by a dedicated tool', which distinguishes it from the ~22 named read siblings. An agent can route to it without opening its schema.

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

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

Gives a clear condition for use: only paths that no dedicated tool covers, and repeats the READ-ONLY / GET-only constraint. It implies but never states the ordering rule (prefer a dedicated tool first), so it falls just short of explicit 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.

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

Adds substantial behavior beyond the single destructiveHint annotation: PATCH /profiles/{path}, body wrapped as { data: {...} }, partial-update semantics ("only included fields change"), and overwrite-vs-preserve behavior. It omits permission requirements and return shape, but does not contradict the destructive hint.

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

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

Front-loads the mutation warning, then packs endpoint, body-wrapping, merge and overwrite semantics into a few dense sentences. No filler, though it runs slightly long on API mechanics.

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

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

For a mutation tool with only destructiveHint and no output schema, the description covers endpoint, partial-update semantics, field merging, and overwrite behavior well. Return values and auth/permission needs remain unstated, which is a minor gap.

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

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

Schema coverage is already 100%, so the schema documents each parameter, but the description still adds API-level meaning: how `fields` merge over typed fields into the wrapped body, what overwriteCustomFields changes, and that `path` is never sent in the body.

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 (updates) and resource (fundraising profile) and enumerates the mutated fields (goal/name/story). It is clearly the write-side counterpart to raisely_get_profile, but it never explicitly names a sibling to avoid, so differentiation 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?

"MUTATES Raisely data" flags the write nature and the endpoint, but there is no explicit when-to-use/when-not guidance relative to siblings like raisely_request or raisely_upsert_user. Usage is only implied by the name and the PATCH detail.

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?

Adds real context beyond the destructiveHint annotation: the exact API call (POST /users/upsert), the { data: {...} } body wrapping requirement, the no-duplicates matching semantics, and the return value. The one meaningful gap is what happens to existing fields on an email match — whether omitted fields are cleared or preserved — which matters for a destructive 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?

One tight paragraph, front-loaded with the mutation warning, then API mechanics, then field guidance, then return value. Every clause carries information — 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?

Handles the nested `fields` object, the required match key, and the return value despite there being no output schema. Only the overwrite-on-match behavior and any auth/permission requirements are left unstated for a tool flagged destructive.

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 goes further by designating email as the match key and by giving concrete example keys (phoneNumber, address, public, private) for the free-form `fields` bag that the schema leaves as unconstrained additionalProperties. That genuinely helps an agent populate the nested object.

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 ('creates OR updates a supporter/donor') and immediately pins down the match key (email), which is exactly what separates an upsert from a plain create. An agent can distinguish it from raisely_get_user or raisely_update_profile without opening the schema.

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

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

Gives clear usage context: use this rather than a plain create because matching by email avoids duplicates. It doesn't name a concrete sibling tool as the alternative (e.g. raisely_update_profile / raisely_get_user) nor state when-not to use it, so it stops short of full routing guidance.

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