raisely

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

Discloses mutation ('MUTATES Raisely data'), the POST endpoint, the { data: ... } wrapper, required API fields, and return value. It also explains the catch-all 'fields' behavior. This goes beyond the destructiveHint annotation with specific 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?

The description is a single dense paragraph; while not broken into sections, every sentence carries essential information. Slightly long but appropriate for the tool's complexity.

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?

Given 10 parameters and no output schema, the description covers the endpoint, required fields, usage context, and return value. It lacks error handling and auth details but is otherwise thorough for a mutating tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying that 'fields' is a catch-all merged over typed fields, explaining amount is in cents, and describing how campaignUuid/profileUuid link the donation, going beyond 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 clearly states 'records a donation' with a specific verb and resource, and specifies it is for OFFLINE/manual donations, distinguishing it from sibling read tools like get_donation or list_donations.

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 says 'use for OFFLINE/manual donations', provides the API endpoint, required fields, and how to link to campaign/profile, giving clear guidance on when and how to invoke the tool.

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 description goes well beyond the destructiveHint annotation. It discloses the API request format ('wrapped as { data: {...} }'), required-by-API fields (path, body, photoUrl), the mechanism for linking to a profile via `fields`, and the return value. This adds significant behavioral context, including a warning about photoUrl being required by the API even though not required in the schema. No contradictions with 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?

The description is four sentences long, with the key 'MUTATES' flag front-loaded. Every sentence provides essential information: API endpoint, required fields, profile linking, and return behavior. There is no redundancy or filler, making it highly efficient.

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 operation with no output schema, the description is remarkably complete. It covers the API endpoint, request body wrapping, required parameters, optional linking, and return value. It also clarifies the distinction between schema-required fields and API-required fields, which is crucial for correct invocation. The tool's complexity (nested `fields` object, profile linking) is well addressed.

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 schema already provides 100% coverage of all parameter descriptions, so the baseline is 3. However, the description adds meaning beyond the schema by explaining that path, body, and photoUrl are required by the API, that profileUuid should be passed through `fields`, and that `fields` merges extra fields. This helps the agent understand the API's expectations and the special role of the `fields` 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?

The description clearly states the tool's purpose: 'publishes a post (a campaign/profile update)' via 'POST /posts'. This distinguishes it from sibling tools like create_donation, update_profile, or raisely_request, which target different resources or operations. The verb 'publishes' and the specific API endpoint make the action 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?

The description provides clear usage context: it is a mutating operation, and it explains how to link a profile via profileUuid through `fields` and how to pass extra fields. While it doesn't explicitly state 'use this instead of X' or list exclusions, the specificity of the POST /posts endpoint and the distinction from siblings like list_posts make the appropriate use case evident.

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 provide readOnlyHint=true, and the description adds useful behavioral context: it verifies credentials, shows privileges, and returns a { data:{...} } shape. This goes beyond the annotation by describing the response format and the API endpoint. It does not mention error handling, but for a read-only auth check this is sufficient.

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 primary purpose. The API endpoint, usage guidance, and return shape are all included without unnecessary repetition or fluff.

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?

Given the tool's simplicity (no params, no output schema), the description fully covers the essentials: what it does, when to use it, what the result looks like. No gaps 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?

The tool has zero parameters and the schema documents them implicitly (empty properties, 100% coverage). With no parameters, the description cannot add parameter meaning, but the description's mention of the API endpoint and response format still provides helpful context. Baseline of 4 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 clearly states the tool verifies credentials and shows the currently authenticated user plus privileges, with a specific verb and resource. It also names the Raisely API endpoint (GET /authenticate), distinguishing it from sibling tools like get_user or get_profile which fetch arbitrary users.

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?

Explicit guidance: 'Use this first to confirm RAISELY_API_KEY works.' This tells the agent when to call it (before other calls) and its purpose as a credential check. No exclusions needed, as the context is inherently clear.

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

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

Annotations already declare readOnlyHint: true, and the description adds the HTTP endpoint (GET /campaigns/{campaign}) and the return envelope ({ data:{...} }), providing useful context beyond the safety hint. It does not mention edge cases like not-found behavior, but for a simple read operation this is adequate.

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 two sentences with zero waste. The first sentence states the action and target, the second provides the API path and return format. Every word earns its place, making it an exemplar of concise tool documentation.

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-campaign fetch with one parameter and read-only annotation, the description covers the essential elements: what it does, the identifier, the API endpoint, and the return structure. No output schema exists, but the description explicitly states the return envelope, completing the picture for an agent.

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

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

Schema description coverage is 100%, so the input schema already fully documents the 'campaign' parameter. The description repeats the same information ('by id or path/slug') without adding any new semantics, so a 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 uses a specific verb ('Fetch') with a clear resource ('single campaign') and enumerates the identifier types (id or path/slug). This clearly distinguishes it from sibling tools like list_campaigns and get_donation, meeting the highest bar for purpose clarity.

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 provides clear context that this tool is for a single campaign rather than a collection, which implies the appropriate use case. It doesn't explicitly name alternatives or exclusions, but the 'single' qualifier and mention of id/path make the intended usage evident without confusion.

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 signals a safe read operation. The description adds value by specifying the API endpoint (GET /donations/{uuid}) and the response shape ({ data:{...} }), which are not in the annotations. No contradictions.

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 concise: two sentences that front-load the purpose, followed by the API endpoint and return format. Every sentence adds relevant information without waste.

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-item fetch with one parameter and a readOnly hint, the description covers the purpose, parameter usage, API path, and return format. No output schema exists, but the return shape is specified, making the tool fully comprehensible.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'by uuid' and the API path includes {uuid}, but it does not add meaning beyond the schema's 'The donation uuid.' Thus, it does not exceed the baseline.

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

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

The description uses a specific verb ('Fetch') and resource ('single donation') with identifier ('uuid'), clearly distinguishing it from sibling list tools like list_donations. It also includes the API endpoint, reinforcing the exact operation.

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 clearly implies the tool is for fetching a single donation by UUID, which is appropriate context. It does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations declare readOnlyHint=true, and the description adds the actual API endpoint 'GET /profiles/{path}' and response envelope '{ data:{...} }'. This provides useful behavioral context beyond the safety hint, though it doesn't detail error handling or edge cases. No contradiction with 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?

The description is concise and front-loaded: one sentence stating the purpose and another giving the API reference. There is no redundant fluff; every part 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 simple read operation with one well-documented parameter, the description is complete. It provides the return shape, which is especially helpful given the absence of an output schema. The tool's simplicity and clear annotation coverage make this fully 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% and the schema already describes the parameter as 'The profile path (URL slug) or uuid.' The description repeats this information without adding new semantics, so it adds no value beyond the schema. The baseline 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 clearly states the action: 'Fetch a single fundraising profile by path.' It specifies the resource (fundraising profile), the method (GET by path), and how to identify it (URL slug or uuid). This distinguishes it from sibling tools like list_profiles (listing) and get_user (user profiles).

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 implicitly conveys when to use this tool: when you need a single profile by path. It does not explicitly mention alternatives or exclusions, but the scope is clear. Given the sibling context, it's evident that list_profiles is for multiple profiles, so the usage context is established.

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 provide readOnlyHint=true. The description adds useful behavioral context: the exact HTTP method and path (GET /subscriptions/{uuid}) and the response wrapper shape ({ data:{...} }). This goes beyond the annotation without contradicting it, though it omits details like error cases or rate limits.

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

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

The description is two sentences and directly front-loads the core action ('Fetch a single subscription by uuid') followed by the API reference and return shape. Every word contributes to understanding; 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 simple read-only tool with one parameter and no output schema, the description is sufficient: it states the endpoint and response envelope. It does not enumerate all response fields, but the output schema is absent and this is a fetch operation, so the description covers the essential context.

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 single required parameter 'uuid' is fully documented in the schema. The description reinforces that lookup is by uuid but adds no new semantic detail beyond that. This meets the baseline for well-covered schemas.

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 specific verb ('Fetch') and resource ('single subscription (recurring donation) by uuid'), clearly distinguishing it from list_subscriptions and other sibling tools. It also provides the exact API endpoint, leaving no ambiguity about what the tool does.

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 clearly indicates when to use this tool: when you need a single subscription identified by uuid. While it does not explicitly name alternatives or exclusions, the contrast with list_subscriptions is implicitly clear. It provides enough context for an agent to select it over list operations.

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 needs only minimal additional behavioral disclosure. It adds the return format ({ data:{...} }), which is useful, but does not mention error cases, auth requirements, or pagination. No contradiction with annotations exists.

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 three purposeful sentences: purpose, endpoint, and return shape. It is front-loaded with the primary action and contains no redundant or extraneous 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-user fetch with one required parameter and no output schema, the description is complete. It explains what, how (endpoint), and what to expect in the response, and the annotations cover safety aspects, making this adequate for the 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 coverage is 100% with the uuid parameter documented. The description reinforces that the user is fetched by uuid but adds no new semantics beyond the schema, aligning with the baseline for high schema coverage.

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

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

The description clearly states the tool fetches a single user (donor/supporter) by uuid, which is specific and unambiguous. It also includes the exact endpoint (GET /users/{uuid}) and return shape, fully distinguishing it from sibling tools like get_profile or get_donation.

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 when a single user by uuid is needed, but does not explicitly contrast with alternatives such as get_profile or get_authenticated_user. No when-to-use or when-not-to-use guidance is provided, though the resource type is clear.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context: the underlying Raisely API endpoint and the return shape { data:[...], pagination }. It does not contradict annotations and adds value without being verbose.

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, API endpoint, return shape. No filler or redundancy. The intent is front-loaded in the first phrase.

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?

Given the rich schema (100% coverage) and readOnly annotation, the description is nearly complete. It provides the API endpoint and return shape, which is important since there is no output schema. It could mention authentication or error cases, but those are not critical for a simple read-only listing tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond what the schema provides; it only reinforces that the tool lists donations for a campaign. This meets the baseline but does not exceed it.

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

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

Description states 'list donations for a specific campaign', which is a specific verb+resource+scope. It distinguishes from sibling list_donations by explicitly scoping to a campaign, and the 'Convenience' label signals it's a filtered convenience wrapper.

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' clearly implies this is the tool to use when you need donations filtered by campaign, as opposed to a general donations list. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the return shape ({ data:[...], pagination }) and the specific GET endpoint, which is useful context beyond annotations, but it does not discuss default ordering, error behavior, or edge cases. This mirrors the TDQS high example where additional context earns a 3.

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 two sentences and zero waste. It front-loads the core purpose ('Convenience: list fundraising profiles for a specific campaign'), then provides the API endpoint and return shape. Every word 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 simple read-only list tool with detailed schema, the description provides the essential context: purpose, endpoint, and return shape. It does not explain when to use this over other list tools or pagination behavior, but the schema covers pagination details. Overall, it is nearly complete for the 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?

The input schema has 100% coverage with all parameters described, including limits, offset, campaign, and the flexible params object. The description itself does not add parameter-level details, but since the schema carries the burden, the baseline 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 clearly states the verb 'list', the resource 'fundraising profiles', and the scope 'for a specific campaign', which distinguishes it from the sibling tool list_profiles. It also names the direct API endpoint, removing any ambiguity about its function.

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' indicates this is a specialized variant of listing profiles, and the phrase 'for a specific campaign' makes the intended use case clear. It does not explicitly mention alternatives like list_profiles, but the sibling list and the scoped wording imply when to use this tool.

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 indicates safe reading, and the description adds meaningful behavioral details: it specifies the return envelope structure ({ data:[...], pagination }) and identifies the underlying HTTP GET endpoint. This goes beyond the annotation and helps the agent anticipate response shape and 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 two tight sentences: a clear purpose statement, an API reference, and a succinct return shape. Every sentence carries value, with no filler or redundancy.

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

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

For a simple list tool with no output schema, the description sufficiently covers the return envelope and pagination. It does not detail authentication or rate limits, but these are not critical for a straightforward read-only list operation. The presence of the params object is acknowledged via the schema, and the overall behavior is clear.

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 limit, offset, and params are already well-documented. The description does not add parameter-level meaning beyond this, but the reference to pagination indirectly relates to limit/offset. Baseline of 3 is appropriate given the schema's completeness.

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 clearly states 'List fundraising campaigns', a specific verb+resource that unambiguously distinguishes it from sibling tools like list_campaign_donations and list_campaign_profiles. The additional 'Raisely API: GET /campaigns' reinforces the exact operation.

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 tool's purpose implies usage when a user needs a list of campaigns, but there is no explicit guidance on when to prefer this over alternatives such as list_campaign_donations. It provides a clear context (fundraising campaigns) but does not articulate exclusions or alternative recommendations.

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?

While annotations already declare readOnlyHint=true, the description adds useful context by documenting the API endpoint and return shape ({ data:[...], pagination }). This goes beyond the annotation and helps the agent understand response behavior, though it does not cover rate limits or pagination mechanics in detail.

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

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

The description is compact, containing three short sentences that each add value: the action, the endpoint, the filtering capability, and the return structure. No unnecessary words or repetition, making it well-structured and easy to scan.

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, the description covers the essentials: endpoint, filter options, and output shape. It does not explicitly clarify the scope (e.g., all donations vs. user-specific), which could be ambiguous given sibling tools, but the schema and annotations fill in most invocation details. Overall, it is sufficiently complete for an agent to use 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?

All three parameters (limit, offset, params) are fully described in the input schema (100% coverage), so the description adds little new parameter-level meaning. Its example filters (campaign, status, sort, order) are largely redundant with the schema's own examples, keeping it at the baseline of 3.

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

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

The description clearly states the tool lists donations and specifies the Raisely endpoint GET /donations, which is a specific verb+resource. However, it does not explicitly distinguish itself from sibling tools like list_campaign_donations or list_user_donations, so it falls short of a 5.

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

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

The description implies usage by mentioning filterable params (campaign, status, sort, order) but does not provide explicit guidance on when to choose this generic tool over specialized siblings. No when-not-to-use instructions are given, so it only meets the baseline for implied usage.

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 readOnlyHint is true, and the description confirms a read-only GET operation. The description adds a note about the return shape ('Returns { data:[...], pagination }') and clarifies what orders are, but it does not disclose additional behavioral traits like pagination limits, rate limits, or authentication requirements. The safety profile is covered by annotations, so the added detail is modest.

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

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

The description is concise, consisting of four short, information-dense sentences. It covers purpose, endpoint, filtering, and a minimal return shape with no fluff or repetition. The structure front-loads the core purpose and then provides necessary technical details, earning a perfect score.

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?

Given the simple scope of the tool (3 optional params, no required fields, no output schema), the description is sufficiently complete. It provides the endpoint, the semantic meaning of orders, filtering capability, and return shape. The schema covers parameter details, and the annotation covers the read-only nature. It stops short of explaining pagination behavior beyond the shape, but that is not critical for a basic list operation.

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?

All three parameters have descriptive entries in the schema (100% coverage per context signals). The description merely echoes 'Filter via `params`' without adding any new meaning beyond the schema's detailed descriptions for limit, offset, and params. The baseline of 3 is appropriate because the schema already handles 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?

The description clearly states the verb 'List' and the resource 'orders', with a parenthetical clarification that orders are 'ticket/product purchases'. This distinguishes it from sibling list tools like list_donations and list_posts. The inclusion of the API endpoint 'GET /orders' further reinforces the specific purpose.

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 a direct instruction to 'Filter via `params`', which is a usage guideline for how to call the tool. However, it does not provide any context on when to use this tool versus alternatives, such as list_donations or list_user_donations, and does not mention any exclusions or prerequisites. The guidance is implied rather than explicit.

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 adds valuable behavioral context beyond this: it specifies the REST endpoint (GET /posts), the filtering mechanism (via 'params'), and the return envelope ({ data:[...], pagination }). No contradictions with annotations were found.

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 four short, information-dense clauses with no redundant language. It front-loads the core action and resource, and every sentence adds distinct value (purpose, endpoint, filter, return format).

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

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

For a simple read-only list tool with no required parameters and no output schema, the description is nearly complete: it defines the resource, the HTTP method, the filtering option, and the return shape. It could explicitly mention pagination behavior, but the return envelope already signals pagination support.

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 three parameters (limit, offset, params) are already well-documented structurally. The description adds only a brief 'Filter via params' note, which aligns with the schema but does not meaningfully enhance understanding beyond what is already present.

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 explicitly states 'List posts' and clarifies that posts are 'campaign/profile updates', distinguishing it from sibling list_* tools for other resources. It also names the exact API endpoint (GET /posts), making the purpose 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?

The description implies this tool is used for listing posts, but it does not explicitly state when to use it versus alternatives like list_profiles or list_campaign_donations. No exclusions or alternative tool references are provided, so usage guidance is implied rather than explicit.

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?

Beyond the readOnlyHint annotation, the description adds that this is a GET operation, supports query-string filtering, and returns a paginated structure { data:[...], pagination }. It also clarifies the scope (individual/team pages) and explicitly names the Raisely endpoint, providing useful behavioral context without contradicting 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?

The description is three concise sentences that front-load the core purpose, then add relevant details about filtering and the return shape. Every sentence contributes useful information without redundancy, making it efficient and well-structured.

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 covers the essential aspects: what it returns, how to filter, and the pagination structure. It is sufficiently complete for an agent to select and invoke the tool correctly, especially given the comprehensive parameter descriptions in the schema.

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 input schema already provides 100% coverage for all three parameters, including descriptions for limit, offset, and the params object. The description adds minimal extra meaning, only offering an additional example 'type' in the filter list. Since the schema does the heavy lifting, a 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 clearly states the tool lists fundraising profiles, specifically individual/team fundraising pages. It distinguishes itself from sibling tools like list_campaign_profiles by describing the general resource (profiles) and reinforcing with the API endpoint GET /profiles.

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 provides implied usage through the filter examples (campaign, type, sort, order), indicating how to narrow results. However, it does not explicitly state when to choose this tool over alternatives like list_campaign_profiles, nor does it mention exclusions or prerequisites. This is sufficient for a general-purpose list but lacks direct comparisons.

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 readOnlyHint=true already signals a safe read operation. The description adds the Raisely endpoint and the return shape { data:[...], pagination }, which provides useful behavioral context beyond the annotation. It does not cover rate limits or auth, but with annotations present, this is sufficient.

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 extremely concise, front-loading the purpose and adding only essential details (endpoint and return shape). Every sentence contributes meaning with no waste.

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 explains the return shape ({ data:[...], pagination }) and the endpoint. Combined with full schema parameter coverage and the readOnly annotation, this is complete for a simple list tool.

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

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

Schema description coverage is 100%, with all three parameters (limit, offset, params) already documented in the schema. The description adds no parameter-specific information, so it meets the baseline of 3.

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

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

The description clearly states 'List saved audience segments' with a specific verb and resource, and adds the Raisely endpoint and return shape. This distinguishes it from sibling tools, none of which target segments.

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 clear context that this tool is for listing saved audience segments. It does not explicitly mention alternative tools or when not to use it, but since no sibling covers segments, the usage context is clear. Lacks explicit exclusions, so not a 5.

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

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

The annotation `readOnlyHint=true` already signals safety, but the description adds behavioral value by specifying the response structure `{ data:[...], pagination }` and the exact Raisely endpoint. This informs the agent about the return format without contradicting the read-only 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?

Two short sentences deliver purpose, endpoint, filtering, and return structure with zero waste. The description is front-loaded with the tool's core function and stays appropriately concise.

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?

Despite having no output schema, the description covers the essential context: the list operation, the API path, the filtering mechanism, and the response shape. Combined with a well-documented input schema and read-only annotation, this is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description's 'Filter via `params`' adds little beyond what the schema already states about `params` being additional query-string filters. No new parameter-level meaning is provided.

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 opens with 'List subscriptions (recurring donations)' – a specific verb and resource that clearly distinguishes it from single-subscription `get_subscription` and other list tools like `list_donations`. Including the endpoint `GET /subscriptions` further anchors the purpose.

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 explains how to filter using `params` and mentions the API endpoint, but it does not explicitly state when to choose this tool over siblings such as `get_subscription` or `list_donations`. Context is clear but lacks direct alternative guidance.

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

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

Annotations already declare readOnlyHint=true, and the description adds the exact HTTP method (GET) and response shape ({ data:[...], pagination }). This goes beyond the annotation by disclosing the return format and pagination, which is useful behavioral context for a read-only endpoint.

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 two sentences with zero filler. It front-loads the purpose ('List tags'), then adds a technical detail (API endpoint) and return shape. Each 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 simple list endpoint with no output schema, the description fully covers the essential context: purpose, API method, and return structure. Parameter details are fully in the schema, so nothing important 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%, as all three parameters (limit, offset, params) have detailed descriptions. The tool description adds no extra parameter semantics, which is acceptable because the schema already carries the full burden. 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 uses a specific verb and resource ('List tags') and clarifies the purpose ('used to label records'). It also names the exact API endpoint (GET /tags), making it unmistakably distinct from sibling list_* tools like list_segments or list_campaigns.

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 clear context for when to use the tool (to retrieve tags), but it does not explicitly contrast with alternatives or state when not to use it. For example, it doesn't mention that list_segments is for segments, not tags, so usage guidance is implied rather than explicit.

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 provide readOnlyHint=true, and the description adds the exact API endpoint and the return shape ('{ data:[...], pagination }'), giving insight into pagination behavior. It does not contradict the annotations and provides useful context beyond the read-only hint, though it does not cover every edge case.

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 a single concise sentence conveying purpose, API reference, and return format without any filler. Each clause adds value, and it is front-loaded with the convenience/use case.

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

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

For a simple read-only list operation with one required parameter and well-described optional params, the description is sufficiently complete: it specifies the endpoint, the return structure, and the scope. However, it doesn't mention the open-ended 'params' object details or how to use it beyond the schema, and there is no output schema to fall back on. Still, the core context is covered, earning a 4.

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 clear descriptions for uuid, limit, offset, and params. The description does not add additional parameter semantics beyond the schema; the endpoint reference indirectly reinforces the parameters but adds minimal new meaning. 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 clearly states 'a donor's giving history' and explicitly names the Raisely API endpoint GET /users/{uuid}/donations, which uniquely identifies the operation as listing donations for a specific user. This distinguishes it from sibling tools like list_donations (general) and get_donation (single donation).

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 for retrieving a specific user's donation history via the 'Convenience' label and the endpoint structure, but it does not explicitly state when to prefer this over alternatives like list_donations or list_campaign_donations. Context is clear but exclusions/alternatives are not articulated.

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 indicates a safe read operation. The description adds value by specifying the HTTP GET method and the return shape ({ data:[...], pagination }), providing useful context about what to expect. No contradiction with 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?

The description is a single, well-structured sentence that front-loads the primary verb and resource. It includes the API endpoint and return format without any unnecessary fluff.

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 list operation, the description is complete: it states the resource, the API endpoint, filtering mechanism, and return structure. Even without an output schema, the agent has sufficient context to invoke the tool appropriately.

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 detailed descriptions for limit, offset, and params. The description's mention of 'Filter via `params`' adds no additional information beyond the schema, which already explains the params object and its use.

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 clearly states the tool's function: 'List users (donors/supporters/fundraisers)'. It distinguishes from siblings like get_user (single user) and list_profiles by specifying the user resource and the GET /users endpoint.

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 provides clear context for when to use the tool—when a list of users is needed—but does not explicitly mention alternatives or exclusions. The sibling tools like get_user and list_profiles imply different use cases, but this description does not spell them out.

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

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

Annotations already declare readOnlyHint=true, but the description adds context: only GET is allowed, full path with query string must be passed, and returns parsed JSON. This goes beyond the annotation and clarifies the expected input format and output type. Minor gap: no mention of error behavior or rate limits, but for a simple GET escape hatch this is sufficient.

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, highly informative and front-loaded with 'Power-user escape hatch'. Every word contributes: path format, read-only constraint, examples, and return type. No fluff.

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 tool with no output schema, the description covers the essential operational details: what it does, when to use it, how to format the path, and what it returns. The presence of strong annotations and a clear input schema means the description doesn't need to repeat those, and it completes the picture effectively.

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%, but the tool description adds value by providing concrete examples ('/subscriptions/{uuid}/donations' and '/donations?limit=50') and emphasizing the need to include the query string and leading slash. This reinforces the schema's description and reduces ambiguity.

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 clearly states it is a 'GET any Raisely API path' tool, acting as an escape hatch for paths not covered by dedicated tools. It uses a specific verb (GET) and resource (Raisely API path), and distinguishes itself from sibling CRUD tools by being the generic fallback.

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 says 'not wrapped by a dedicated tool', providing a clear when-to-use condition. Also states 'READ-ONLY — only GET is allowed', which is a clear exclusion for write operations. This tells the agent when to choose this tool over the many dedicated 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?

Adds substantial behavioral detail beyond the destructiveHint annotation: partial update semantics ('only included fields change'), the requirement to wrap the body as { data: {...} }, the overwriteCustomFields behavior, and the fact that path is never sent in the body. These are valuable for predicting side effects. No contradiction with 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?

The description is appropriately concise: three sentences that are information-dense and front-loaded with the primary action. Every sentence contributes essential details without redundancy.

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

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

Covers the tool's core behavior, partial update semantics, and a custom field quirk. However, since there is no output schema, the description does not mention what the tool returns or error behavior, leaving some incompleteness for an agent expecting a response format.

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 descriptions cover all parameters, so the description goes beyond by clarifying how `fields` maps to goal/name/story and other attributes, and how the body should be wrapped. This adds integration context, though the schema already handles most parameter meaning.

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

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

The description clearly states the tool updates a fundraising profile, naming specific fields (goal/name/story) and the REST endpoint. It is unambiguous and distinguishes this from the many sibling read/list tools as well as create tools.

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

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

The description provides clear context for when to use the tool (updating profile attributes) and explains the API mechanics, but it does not explicitly contrast it with alternatives like raisely_request or state when not to use it. Still, the intended use is easy 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?

The description discloses mutational behavior ('MUTATES', 'creates OR updates'), explains the email matching logic, and provides API endpoint and body wrapping details. This goes beyond the destructiveHint annotation by adding technical context, though it omits some edge-case behaviors like field overwrite semantics.

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 compact and front-loaded with 'MUTATES Raisely data', then delivers purpose, API usage, parameters, and return value in two dense sentences. Every sentence earns its place with no redundancy.

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

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

Given the tool has 4 parameters, only a destructiveHint annotation, and no output schema, the description covers purpose, usage, API details, and return value. It provides enough context for an agent to invoke the tool correctly, and the lack of return format details is acceptable without an output schema.

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 input schema already describes all 4 parameters including the email match key and `fields` merge behavior. The description repeats the 'everything else via fields' guidance without adding new parameter-level meaning, so it stays at the baseline for high schema coverage.

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

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

The description clearly states the tool creates OR updates a supporter/donor matched by email, using a specific verb and resource. It distinguishes itself from a plain create by noting 'no duplicates', which separates it from sibling tools.

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

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

The description gives clear context for when to use this tool: 'safer than a plain create — no duplicates'. It also explains how to handle additional fields via `fields`. However, it does not explicitly name alternative sibling tools or state exclusion criteria, so it stops short of a 5.

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