Bloomerang MCP by usefulapi

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

Annotations only carry destructiveHint=true; the 'WRITE:' prefix is consistent with that and adds mutation framing. The dedupe warning usefully implies the API will not block duplicates on its own, but there is no disclosure of permissions, error behavior, or reversibility for a 20-parameter write tool.

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

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

Three tight sentences, front-loaded with the write indicator and the type-conditional rule, with no filler. The trailing 'Bloomerang: POST /constituent' is minor noise that earns little but costs little.

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 20-parameter nested-object write with no output schema, the description covers the hardest part — which name fields each type requires — plus the duplicate-prevention workflow. It omits any hint of what is returned (e.g. the new constituent ID) and doesn't flag the CRM-configured-value constraints on prefix/suffix/state beyond what the schema already says.

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 only 45% and the schema marks just 'type' as required, so the description's conditional rule — first_name/last_name for Individual, full_name for Organization — supplies required-field semantics the schema omits entirely. Remaining parameters (gender, employer, website, etc.) are self-explanatory and left to 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 ('create a new individual or organization constituent') and immediately distinguishes the two creation modes. It is trivially separable from siblings like bloomerang_update_constituent, bloomerang_get_constituent, and bloomerang_create_note without opening any schema.

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

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

It gives an explicit pre-condition and routing rule: search with bloomerang_search_constituents first to avoid duplicate donors. That names the alternative tool and the condition selecting it, though it doesn't state when *not* to create or how duplicates are handled if one is found.

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 disclose destructiveHint=true, so the safety profile is partly covered. The description adds that the record lands on the constituent's timeline and the backing endpoint (POST /interaction), but says nothing about required permissions, idempotency/duplicate risk on retry, or whether the entry can be edited or removed.

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

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

Two tight sentences with the write intent front-loaded via the "WRITE:" prefix. The trailing "Bloomerang: POST /interaction" is mildly redundant detail but does not clutter the core message.

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?

Adequate for a 5-required-parameter mutation with no output schema. It tells the agent what the tool creates, but omits what happens on success, whether omitted optional fields default, and which fields are mandatory — gaps that matter given the schema alone must carry the rest.

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 documents all 7 parameters and the enums already carry their own descriptions. The description only echoes channel examples (call, email, meeting, letter) and gives no additional syntax, format, or dependency guidance, 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 concrete verb+resource ("log an interaction with a constituent") and clarifies the storage location ("on their timeline"), with examples that map to the channel enum. It does not explicitly distinguish this from create_note or create_task, which an agent could plausibly confuse it with.

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 guidance and no named alternatives, even though create_note, create_task and list_interactions sit in the same sibling set. The agent must infer the boundary between logging an "interaction" and creating a "note".

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 supply only destructiveHint=true, so the description must carry the rest of the burden. It confirms the write nature ('WRITE') and the underlying endpoint, but discloses nothing about what the mutation affects, whether it can be undone, or what confirmation is returned.

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, front-loaded sentences with no filler; the WRITE marker and resource lead. It is terse to the point of omitting anything else useful, but nothing present is wasteful.

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 low-complexity three-param write with full schema coverage and no output schema, the essentials are present. However, with only a destructiveHint annotation, the description leaves auth requirements and success behavior unexplained.

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 params documented in-schema, including the useful 'API Id, not AccountNumber' distinction, so the baseline is 3. The description itself adds no parameter-level meaning beyond that.

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 ('add a note to a constituent's record'), which cleanly separates it from siblings like bloomerang_create_interaction, bloomerang_create_task, and bloomerang_list_notes. It does not explicitly name those siblings, 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 says what the tool does but gives no when-to-use guidance, no prerequisites, and never mentions the alternative write tools (interaction, task) an agent might confuse it with. Usage is only implied by the resource name.

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 only destructiveHint=true and a title, so the description must carry the behavioral load. It correctly labels the operation as a WRITE and names the underlying endpoint, but says nothing about side effects such as whether notification emails fire by default or what permissions are required. Note the destructiveHint=true annotation is unusual for a create operation, but the description does not contradict it.

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

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

Two compact sentences with no waste; the write-nature and core purpose are front-loaded, then the parameter-sourcing hint. Every clause earns its place.

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

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

For an 8-parameter mutation tool with no output schema and thin annotations, the description covers purpose, optional linkage, user-ID sourcing, and the endpoint. The remaining gaps (default notification behavior, permission requirements) are minor since send_notifications is documented 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine value by explaining how to obtain assignee_user_id (via bloomerang_get_current_user or existing tasks) and that constituent linkage and assignment are optional. It does not restate the enum semantics for channel/purpose, which the schema already covers.

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 ('create a follow-up task') plus its optional scoping ('tied to a constituent and assigned to a user'), which differentiates it from the sibling create_note and create_interaction tools. The 'WRITE:' prefix and the raw endpoint (POST /task) make the operation 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?

It gives a concrete sourcing hint for the assignee parameter ('find user Ids via bloomerang_get_current_user or existing tasks'), which is a real routing cue. However, it offers no when-to-use-this-vs-alternatives guidance relative to bloomerang_create_note or bloomerang_create_interaction, which are the closest 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 usefully discloses the payload contents (names, contact details, household, preferences, engagement score, custom values), which matters because there is no output schema, and maps the tool to GET /constituent/{id}. It still omits error/not-found behavior and any auth or rate-limit 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?

Two compact sentences, front-loaded with the action and the returned profile fields. The trailing endpoint mapping is slightly boilerplate but still informative; 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 single-parameter read-only getter with no output schema, enumerating the returned fields largely compensates for the missing output schema, so an agent knows what it will get back. The remaining gap is routing context (how to obtain a valid constituent_id) rather than payload description.

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 carries the important note that this is the API Id, not the CRM AccountNumber. The description's '{id}' merely restates the parameter and adds no syntax, range, or format detail beyond 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 ('Fetch') and resource ('one constituent's full profile'), plus an enumeration of returned fields. It is clearly distinguishable from bloomerang_list_constituents and bloomerang_search_constituents by the singular, id-based scope, though it never names those siblings explicitly.

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

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

Usage is only implied: the singular 'one constituent' plus the /{id} template signal that an id is required. There is no when-to-use guidance, no statement that an id must be obtained from search_constituents or list_constituents first, and no exclusions versus get_constituent_timeline.

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?

With readOnlyHint=true already covering the safety profile, the description still adds real behavioral context: results are ordered newest first, the timeline aggregates multiple record types, and a household Id fans out to all members. It does not discuss pagination behavior, but the schema documents skip/take.

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 front-loaded sentences that state contents and ordering before the household nuance, plus a compact endpoint reference. 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 read-only, non-paginated-in-description lookup with no output schema, the description covers what is returned and in what order. Pagination controls and Id constraints are handled by the schema, so little is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the effect of passing a household Id (timeline of every member) rather than just restating that the field accepts a household.

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

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

Names a specific resource (activity timeline for a constituent) and enumerates its contents (gifts, interactions, notes, tasks), with ordering stated. It is clearly distinct from siblings like bloomerang_list_interactions or bloomerang_list_notes, which return single activity types.

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 one conditional usage rule — pass a household Id to get every member's timeline — but never states when to prefer this consolidated timeline over the sibling list_* tools. Usage is implied rather than explicitly routed.

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 only provide readOnlyHint=true; the description adds the useful facts that the identity is derived from the API key itself and that the result carries a permission level useful for capability checks. It stops short of describing error behavior when the key is invalid, but the added context is meaningful 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?

Two tight sentences plus an endpoint reference; the core purpose is front-loaded and no sentence is filler.

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

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

With no output schema, the description compensates by naming the returned fields (name, email, permission level), and the tool takes no arguments, so an agent has everything needed to call and interpret it.

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?

Zero parameters, so there is nothing for the description to disambiguate and the baseline is a 4. It correctly implies no input is 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?

States a specific verb and resource: fetch the Bloomerang user tied to the current API key. The returned fields (name, email, permission level) further pin down what 'user' means, and it is clearly distinct from every constituent/transaction sibling.

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 frames usage as a cheap credential/authorization check ('confirm the key works and see what it may do'), which tells the agent when this is the right call. It does not name alternatives or exclusions, but no sibling overlaps with this purpose.

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=true already establishes the safe-read profile, and the description adds value beyond that by disclosing the shape of the response (names, HeadId, member constituent Ids) and the underlying API route. There is no mention of permissions, pagination, or error behavior, but for a read-only lookup the remaining burden is light.

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 plus a compact endpoint reference, with the return payload front-loaded before the data-model note. No filler, and every clause carries either scope or content 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 carries the return-value burden, and it does list the key fields a caller would rely on. It is not exhaustive about the household object's full attribute set, but it is sufficient for an agent to decide whether to call it and what to expect.

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 explains that household_id is the API Id rather than the CRM AccountNumber, so baseline 3 applies. The description reinforces the distinction between HouseholdId and other identifiers but adds no format, range, or lookup guidance 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 household') and immediately enumerates the returned payload — names, HeadId, member constituent Ids — so the agent knows exactly what this returns versus a constituent fetch. The note that 'A constituent's HouseholdId points here' plus the endpoint mapping (GET /household/{id}) distinguishes it from the sibling get_constituent 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 line 'A constituent's HouseholdId points here' gives the agent a real trigger condition: fetch this when you have a HouseholdId surfaced from a constituent record. It stops short of naming an alternative or stating when-not to use it (e.g., use get_constituent for an individual), so no explicit exclusions are present.

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, so the safety profile is covered; the description goes beyond that by enumerating the returned payload (payment method, amounts, refund status, every designation type), which is the only disclosure of return content since no output schema exists. It omits error/not-found behavior and permission requirements, 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?

Two tightly packed sentences, with the resource and returned fields front-loaded and the API endpoint appended as reference. 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?

With no output schema, the description sensibly compensates by naming the returned fields, and the endpoint path aids orientation. It is nearly complete for a single-read tool, lacking only failure-mode behavior (invalid or missing id) and 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% and the schema already documents that the id is the API Id rather than the CRM AccountNumber, so the description adds no parameter meaning beyond it. Baseline 3 is appropriate when the schema does all the work.

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

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

Specific verb ('Fetch one transaction') plus the exact resource and the fields it returns (payment method, amounts, refund status, designations). The singular scope cleanly distinguishes it from bloomerang_list_transactions without opening either schema.

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

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

No when-to-use guidance and no routing to alternatives — it never says to call bloomerang_list_transactions first to obtain a transaction_id, nor what to do when the id is unknown. The single-use case is implied by the name, but nothing is 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?

readOnlyHint=true already establishes the read-only profile, so the bar is lower. The 'Bloomerang: GET /appeals' line reinforces a safe read but adds little beyond the annotation; pagination behavior, result shape, and default ordering are left to the schema.

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

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

Single front-loaded sentence with a concrete parenthetical example, followed by a short API pointer. No waste, though the 'Bloomerang: GET /appeals' tail is marginally redundant with the readOnly annotation.

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 6-param filtered list tool with no output schema, the description characterizes the resource adequately but says nothing about return contents or the practical effect of skip/take/search. Minimum viable, with clear gaps.

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 ids/skip/take/search/is_active/last_modified are already documented in the schema. The description adds no parameter syntax or filtering guidance, 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?

Clear verb+resource ('List appeals') with a domain gloss that explains what an appeal is ('the specific asks... that gifts are attributed to'). This differentiates it from generic list tools, though it never names how it differs from siblings like list_campaigns or list_funds.

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

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

No when-to-use guidance, no alternatives named, no mention of when to reach for list_appeals versus list_campaigns/list_funds or the search endpoint. The agent must infer usage entirely from the resource name.

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 safe-read profile is covered. The description adds only the returned fields and the underlying endpoint; it says nothing about result size, pagination behavior, or total counts, which the schema's skip/take parameters imply is relevant.

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, purpose front-loaded with no filler. The 'Bloomerang: GET /campaigns' fragment is cheap and mildly useful for endpoint mapping, though it borders on redundant with the title.

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

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

With no output schema, the description should carry more of the return-value burden; it names goals and dates but omits pagination shape and record fields. Given fully documented parameters and read-only annotations, it is adequate but not complete.

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

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

Schema description coverage is 100%, so all seven filters (ids, skip, take, search, has_goal, is_active, last_modified) are already documented in the schema. The description adds no filtering semantics or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List fundraising campaigns') plus the fields returned (goals and dates), so the purpose is unambiguous. It does not explicitly differentiate itself from sibling list tools such as list_appeals or list_funds, but the resource name alone is distinctive enough to route correctly.

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

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

No when-to-use guidance, no exclusions, and no mention of alternatives (e.g., search_constituents-style search or get-by-id tools). The agent must infer usage purely from the name and schema filters.

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=true already tells the agent this is a safe read, so the bar is lower. The description adds useful content on what is returned (relationships plus the role on each side) and maps to the underlying GET endpoint, but says nothing about pagination limits, permissions, or result ordering 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?

One sentence stating the resource contents followed by the endpoint mapping – no filler, and the substantive information is front-loaded.

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

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

For a read-only list tool with full schema coverage and no output schema, the description adequately tells the agent what comes back (relationships with roles on both sides). It could mention paging behavior or that results are scoped to one constituent, but the schema covers those gaps.

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% – skip, take, last_modified, and constituent_id are all documented in the schema, including the note that constituent_id is the API Id rather than the CRM AccountNumber. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description names the resource precisely ('relationships between this constituent and others') and gives illustrative relationship types (spouse, employer, board member), so it is clearly distinguishable from siblings like get_constituent or list_constituents. It never states the verb 'list' itself, relying on the title and name to supply that, which slightly weakens standalone 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?

There is no guidance on when to use this tool versus alternatives such as get_constituent or get_constituent_timeline, and no prerequisites or scoping advice. Usage is only implied by the resource noun.

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=true already tells the agent this is a safe read with no side effects, lowering the bar. The description adds the date-range sync use case but says nothing about result volume, pagination semantics, or how the custom_field_id/custom_field_value pair must be used together.

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?

Compact and front-loaded: purpose, filter list, usage hint, endpoint mapping, with no filler. The em-dash filter enumeration is slightly dense but every clause carries information.

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

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

For a 10-parameter list tool with no output schema, the description covers what can be filtered and one use case but omits result-set behavior and paging expectations an agent would need when syncing, and never positions itself against the search sibling.

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 80%, so the schema already documents most parameters including defaults and ranges. The description restates the filter categories the schema already names and adds no syntax, pairing rules, or default behavior of its own, making baseline 3 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 (List) and resource (constituents) and enumerates the filter dimensions (Id, type, favorites, last-modified, custom field) plus sorting. It does not, however, distinguish itself from the sibling bloomerang_search_constituents, which an agent could easily confuse with this tool.

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?

'Good for syncing recent changes' gives one concrete usage scenario, implying the last_modified filter path. But there is no explicit when-not guidance and no mention of search_constituents or get_constituent as alternatives, so selection between the three constituent-reading siblings is left to inference.

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

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

readOnlyHint=true already declares the safe read profile, so the description need not restate that. It adds useful domain context (funds are designatable targets for gifts) and the backing endpoint, but says nothing about pagination behavior despite skip/take parameters.

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

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

Two short sentences, front-loaded with the purpose before the endpoint reference. No wasted wording, though the raw 'Bloomerang: GET /funds.' line is marginal value for an agent.

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-required-parameter read-only list tool, the safety profile, filters, and pagination are all covered by annotations and a fully-described schema, so the description is sufficient. Only the absence of any output-shape hint keeps it from a 5.

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

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

Schema coverage is 100% – every one of the six parameters carries its own description including defaults and ranges. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (funds), and clarifies the domain meaning with examples ('General Operating, Scholarship'). It is clearly distinguishable from sibling list_* tools by resource, though it never names them explicitly.

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

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

No guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. Retrieval intent is implied by 'List', but nothing tells the agent the context in which funds should be enumerated.

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=true already declares this as a safe read, so the description is not carrying the full burden. The 'Bloomerang: GET /interactions' mapping adds modest confirmation of the read-only, endpoint-backed nature, but says nothing about result caps, default ordering behavior, or cost.

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

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

A single dash-separated sentence: purpose first, filter capability second, endpoint reference last. No filler, and the most important information is front-loaded.

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

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

Annotations cover safety and the schema covers all eight parameters, but because there is no output schema the description could reasonably say what a result looks like (paginated interaction records, default ordering by Date). As written, an agent must infer the return shape entirely from the parameter set.

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 eight fully documented parameters, so the schema does the heavy lifting and baseline 3 applies. The description's mention of constituent, channel and purpose filtering mirrors the schema without adding syntax, defaults, or interaction between filters.

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

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

States a clear verb (List) and resource (interactions), and enumerates concrete interaction types (calls, emails, meetings, letters) so the agent knows what domain this covers. However it does not differentiate itself from siblings like bloomerang_get_constituent_timeline, which likely also surfaces interaction data.

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 'filter by constituent, channel or purpose' implies the search-oriented use case and maps to real parameters, giving implicit guidance. There is no explicit when-to-use vs alternatives statement, nor any exclusion such as when a timeline or single-interaction fetch is preferable.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the API mapping ('Bloomerang: GET /notes') but says nothing about pagination or return shape beyond what the schema's skip/take already provide.

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

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

Two short sentences with zero waste; the core action and its optional scope are front-loaded before the endpoint reference.

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

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

For a simple read-only list endpoint with full schema coverage and readOnlyHint, the definition is largely complete. It could note default sort/paging behavior, but that is already captured in the schema descriptions.

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

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

Schema coverage is 100%, so all six parameters are already documented in the schema, giving a baseline of 3. The description's 'optionally for specific constituents' restates the constituent_ids filter but adds no syntax or format detail beyond the schema.

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

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

States a clear verb+resource ('List notes') and adds the optional constituent scoping, so an agent immediately knows what it retrieves. It does not differentiate itself from sibling list tools (list_interactions, list_tasks, list_constituents), but the resource 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?

The phrase 'optionally for specific constituents' implies a filtering use case, which is minimal guidance. There is no explicit when-to-use vs. alternatives (e.g., search_constituents or create_note) and no 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?

readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds the underlying endpoint mapping (Bloomerang: GET /tasks), which reinforces read-only behavior, but discloses nothing about pagination behavior, result limits, or default ordering. Modest added value beyond 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?

Two tightly written sentences, filter dimensions front-loaded, with the API mapping tacked on last. No wasted words and 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?

Description summarizes filterable fields but omits the ordering (order_by/order_direction) and pagination (skip/take) capabilities present in the schema. With no output schema, return shape is unaddressed, though that is not required. Adequate but with clear gaps for a 12-parameter 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 75%, so most parameters are already documented in the schema (skip, take, dates, ids). The description restates the filter dimensions (status, due-date range, assignee, constituent, channel, purpose) without adding format or default details beyond what the schema provides. 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 (tasks), clarifies the resource as follow-ups, and enumerates the dimensions the listing can be filtered by. An agent can distinguish it from create_task and from sibling list tools like list_interactions without opening the schema.

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

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

The filter list implies the retrieval use case, but there is no explicit when-to-use guidance or when-not statement, and the sibling create_task is never named as the alternative for creating a task. Usage is left to inference from the description.

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?

'Read only' merely restates readOnlyHint=true, so it earns no credit; the useful addition is the underlying GET /transactions endpoint mapping. It does not disclose pagination/limit behavior, ordering defaults, or result shape beyond what the schema already provides, and with annotations present the bar is lower.

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 that are front-loaded with the core purpose and end with the API mapping; every clause (subtypes, designations, filters, read-only) carries information with 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 an 11-parameter, all-optional list tool with full schema coverage and no output schema, the description covers purpose, entity scope, and filter capabilities adequately. It could say more about pagination/ordering behavior, but the schema already documents skip/take/order_by/order_direction.

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 11 parameters are already documented with meaningful descriptions in the schema. The description's filter list mirrors the schema without adding format, syntax, or interaction details, 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 (List) plus resource (transactions) and enumerates the transaction subtypes covered (donations, pledges, pledge payments, recurring donations and payments) as well as the attached designations. This clearly separates it from the singular bloomerang_get_transaction and from the list_* 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 spells out the available filter dimensions (constituent, amount range, type, last-modified date), which implies when the tool is useful, and 'Read only' signals safe use. However, it never explicitly says when to use this instead of bloomerang_get_transaction or the other list tools, so the routing is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that this is a full-text (not exact-match) search and cites the underlying GET endpoint, but says nothing about matching behavior, result ordering, or empty-result handling beyond what the schema shows.

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 with zero filler; the search scope is front-loaded and the routing cue ('start here') follows immediately.

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 search tool with fully documented parameters, the description covers what to search, what it covers, and why to reach for it first. With no output schema present it could say slightly more about what comes back (e.g., constituent summaries with Id), though 'find a donor's Id' implies the key return value.

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 skip, take, type, and search are all fully documented in the schema. The description's mention of name/email and the three record types restates rather than extends that, which is the expected 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?

States a specific verb (full-text search) and resource (constituents) with explicit scope: individuals, organizations, and households, plus the searchable fields (name, email). An agent can distinguish this from bloomerang_list_constituents (enumeration) and bloomerang_get_constituent (single-record lookup) 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?

"Start here to find a donor's Id" gives a clear entry-point cue for the common workflow. It does not explicitly contrast with alternatives such as bloomerang_list_constituents, so the when-not-to-use case is left to inference.

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

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

Annotations already flag destructiveHint=true, so the mutation risk is known. The description adds genuinely new behavioral context: this is a partial update where unspecified fields are untouched, and it names the underlying PUT /constituent/{id}. It omits auth/permission requirements and any reversibility or rate-limit notes, keeping it out of 5 territory.

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, front-loaded segments: the operation, the partial-update rule, and the API mapping. Zero filler; every clause carries information an agent needs.

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 20-parameter mutation with nested objects, no output schema, and sub-50% schema coverage, the description is only moderately complete. It communicates partial-update semantics and field categories, but says nothing about error handling, permission requirements, or what happens to fields deliberately excluded from the payload.

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 only 45% across 20 parameters (including nested primary_email/phone/address objects), so the description carries part of the burden. It does helpfully group the updatable fields into names/job/status/primary contact info, but adds no per-parameter format or constraint detail beyond what the schema already documents.

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 (update) plus resource (existing constituent profile) and enumerates the field groups affected (names, job, status, primary address/email/phone). The word 'existing' and the WRITE prefix cleanly separate it from bloomerang_create_constituent and the get_/list_ read 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?

'Only the fields you supply are sent' implies patch-style partial updates, which is real usage guidance, but there is no explicit when-to-use vs when-not, no prerequisites (e.g. permissions), and no named alternative for creating a new constituent. Usage is implied rather than stated.

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