bloomerang

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

The destructiveHint=true annotation already declares this is a mutating write, and the 'WRITE:' prefix merely confirms it. The description adds the non-idempotent/duplicate-creation trait via the 'search first' warning and the POST endpoint, but discloses nothing about permissions, side effects, or what 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?

Four short, front-loaded clauses with no filler: the write nature leads, then field guidance, then the duplicate-avoidance instruction. Every sentence earns its place.

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

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

Core create semantics and the critical individual-vs-organization branching are covered, which suits a 1-required-param tool. But given 20 parameters, nested objects, and no output schema, the omission of return-value information and the many optional fields leaves the picture only partially 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?

With 20 parameters and only 45% schema coverage, the description carries real weight by mapping the required 'type' to the correct name fields (individual -> first_name/last_name, organization -> full_name), which the schema does not express as conditional logic. However, the other ~18 optional parameters get no explanation, leaving much of the schema's gap unfilled.

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 ('create a new individual or organization constituent') and immediately branches on the type, so the agent knows exactly what the tool produces. It is clearly distinct from the search/get/update/list siblings by its create action.

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

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

Explicitly routes the agent to call bloomerang_search_constituents first to avoid duplicate donors, which is a strong when-to-use alternative with a named sibling. It doesn't state a when-not condition or point to bloomerang_update_constituent for existing records, so it stops short of full routing guidance.

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

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

The 'WRITE:' prefix reinforces the destructiveHint=true annotation without contradicting it, and the description adds that the entry lands on the constituent's timeline. It does not mention permissions, whether the write is reversible, or any 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?

Two tight clauses, front-loaded with the WRITE cue and the operation's effect. 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 7-param write tool with no output schema, the description covers the core action and timeline placement but omits what is returned on success and how it differs from writing a note. Adequate but 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 the schema fully documents all 7 parameters including the required date/channel/purpose/subject fields. The description adds no syntax or format detail beyond that, 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?

Specific verb ('log/create') and resource ('interaction') with examples (call, email, meeting, letter) scoped to a constituent's timeline. It's clearly differentiated from get/list siblings, though it doesn't explicitly contrast with the close sibling bloomerang_create_note.

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

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

No when-to-use or when-not-to-use guidance. Given siblings like create_note, create_task, and list_interactions, the agent gets no help deciding which is appropriate for a given situation.

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 and a title, leaving the description to add behavioral context. 'WRITE' and 'POST /note' restate the obvious write nature rather than disclosing anything new, such as whether the note appears on the constituent timeline, permission requirements, or whether it is editable afterwards. No contradiction with the annotations, but minimal added value.

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 fragments are front-loaded and waste no words, but 'Bloomerang: POST /note' is endpoint trivia that gives the agent no decision-relevant information and partly duplicates the WRITE prefix and the tool name.

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 three-parameter write with full schema coverage and no output schema, the description is just minimally adequate. It omits any expected outcome (e.g., created note id) and any note about the surprising destructiveHint=true annotation on what reads like an append 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?

Schema description coverage is 100%, so all three parameters (including the important disambiguation that constituent_id is the API Id, not the AccountNumber) are already documented. The description adds no field-level meaning beyond that, which is the expected baseline when the schema does 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?

The description gives a clear verb+resource ('add a note to a constituent's record') that an agent can act on immediately. It does not differentiate from the sibling bloomerang_list_notes or bloomerang_create_interaction, but the write semantics are unambiguous.

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

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

There is no guidance on when to use this versus bloomerang_create_interaction or other timeline-writing siblings, and no prerequisites or exclusions stated. The reader must infer usage entirely from the tool 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?

The 'WRITE:' prefix and POST /task endpoint disclose that this is a mutating call, which is the main behavioral fact. However, it says nothing about the notification side effect (deferred entirely to the schema), required permissions, or whether the new task is returned. Annotations carry only destructiveHint, so the description could do more.

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: the write operation and its scope come first, followed by the ID-sourcing hint and the endpoint. The 'Bloomerang: POST /task' tail is mildly redundant but harmless.

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 create tool with no output schema, the description covers the relationship fields but never says what is returned (e.g., the new task ID) or mentions the send_notifications side effect, leaving the agent to infer the response shape.

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, but the description goes beyond the schema by explaining how to source the non-obvious assignee_user_id and by framing constituent_id/assignee_user_id as optional relationships.

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 ('create a follow-up task') plus scope modifiers (optionally tied to a constituent, assigned to a user). It is clearly distinguishable from the sibling bloomerang_list_tasks and the other create_* tools, which target different resources.

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?

Provides a useful routing hint for obtaining assignee IDs ('find user Ids via bloomerang_get_current_user or existing tasks'), but gives no guidance on when to create a task versus a sibling create tool such as bloomerang_create_interaction or bloomerang_create_note, nor any prerequisites.

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, and the description adds the endpoint (GET /constituent/{id}) and the breadth of returned profile data, which matters since no output schema exists. It stops short of noting behavior for missing/inactive constituents.

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

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

Two sentences, zero filler: the returned-data scope comes first and the API mapping second. Nothing is 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?

For a one-parameter read tool with no output schema, listing the returned fields largely compensates for the missing return documentation. Error/not-found behavior is the only notable omission.

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

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

Schema coverage is 100% and the sole parameter is fully documented in the schema (including the API-Id-vs-AccountNumber distinction), so the description adds no parameter detail. Baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one constituent's full profile') and enumerates the payload scope (names, contact details, household, preferences, engagement score, custom values), which clearly separates it from the list/search/get_household 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?

Usage is implied by the singular 'one constituent' plus the required API id, but there is no explicit statement of when to prefer this over bloomerang_search_constituents, bloomerang_list_constituents, or bloomerang_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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context (aggregated multi-type feed, newest-first ordering, household expansion) but says nothing about pagination behavior or the offset/limit implications despite skip/take existing.

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 zero waste: content and ordering are front-loaded, the household case follows, and the API path is a compact trailing 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?

No output schema exists, but the description names the returned item types and ordering, and the schema fully documents pagination. For a read-only, three-parameter tool this is largely complete, though return-shape detail (e.g. pagination limits on results) is not 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?

Schema coverage is 100%, so constituent_id, skip and take are already documented, giving a baseline of 3. The description adds genuine meaning beyond the schema by explaining that a household Id expands to every member's timeline, which the schema's parenthetical does not fully convey.

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

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

States a specific verb+resource ('activity timeline for a constituent') and enumerates the content types it aggregates (gifts, interactions, notes, tasks), which implicitly separates it from the single-entity list siblings. It does not, however, explicitly name an alternative such as bloomerang_list_interactions, so the differentiation is inferred rather than stated.

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

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

The description gives one conditional usage note — pass a household Id to get every member's timeline — but offers no when-to-use vs when-to-use-something-else guidance relative to the many list/get siblings. Usage is implied by the resource rather than explicitly scoped.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that by noting the call is cheap and discloses the returned identity/permission fields, though it says nothing about rate limits or error behavior for an invalid key.

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

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

Three short sentences, identity/purpose front-loaded, and the endpoint reference kept to a trailing clause. Every sentence earns its place 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?

No output schema exists, so the description carries the return-value burden and does so by naming the returned fields. For a zero-parameter read tool with readOnlyHint, the definition is complete enough to invoke 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 tool takes zero parameters, so there is nothing for the description to disambiguate; encoding the endpoint (GET /user/current) is a minor bonus. Baseline 4 applies for a parameterless tool.

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 (the current API-key user), and enumerates the returned fields (name, email, permission level). It is clearly distinguishable from the constituent/transaction/list siblings, none of which concern the authenticated user.

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?

Provides a clear use context: 'a cheap way to confirm the key works and see what it may do.' This tells the agent when it is useful (key validation, permission discovery) but names no alternative tool or exclusion condition.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the data-shape disclosure (names, HeadId, member Ids), which helps the agent parse the response even without an output schema. It says nothing about pagination, auth scope, or behavior for missing/invalid ids.

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 plus an endpoint note. The return payload is front-loaded and nothing is padded.

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

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

For a single-parameter read tool with full schema coverage and annotations covering safety, this is essentially complete. The only minor gap is that it doesn't state what the endpoint returns on a missing household, but no output schema or error model is promised.

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 parameter description already warns 'not the CRM AccountNumber'. The description reinforces the linkage model (constituent HouseholdId → this id), which adds relational meaning beyond the schema's type constraint, nudging above the baseline 3.

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

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

States a specific verb (Fetch) and resource (a household) and enumerates exactly what's returned — names, HeadId, member constituent Ids. That concrete field list distinguishes it from bloomerang_get_constituent, which is the key sibling an agent could 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?

The line 'A constituent's HouseholdId points here' tells the agent the routing condition — use this when you have a HouseholdId from a constituent record. It stops short of explicitly naming bloomerang_get_constituent as the alternative for individual records, but the context 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?

readOnlyHint=true already declares this as a safe read. The description adds value by disclosing the shape of the returned record (designations, acknowledgement status, refund status), which is useful since there is no output schema, but it says nothing further about auth, errors, or missing-record behavior.

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

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

Two tight sentences that front-load the operation and payload before the endpoint mapping. Nothing is padded, though the trailing endpoint string is mildly redundant 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 single-parameter read with no output schema, the description usefully enumerates what the returned transaction contains, which partly compensates for the absent output schema. It is nearly complete, missing only an explicit routing note against the list 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 coverage is 100% and the schema itself documents the key nuance (API Id, not CRM AccountNumber). The description adds no parameter detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (one transaction) and enumerates the notable payload sub-resources (payment method, amounts, refund status, designations). It is clearly distinguished from bloomerang_list_transactions by the singular 'one transaction', though it does not name that sibling explicitly.

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

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

Usage is only implied: 'one transaction' combined with the required transaction_id signals this is the single-record lookup, versus the list tool. There is no explicit statement of when to prefer this over bloomerang_list_transactions or any precondition 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?

The readOnlyHint annotation already establishes that this is a safe read operation, and the description aligns with that by noting GET /appeals. It adds domain context about what an appeal is, but does not disclose pagination behavior, authentication requirements, rate limits, or return shape beyond what annotations and schema already cover.

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 short, front-loaded sentences with no wasted words. The endpoint reference is concise and useful for identifying the underlying API call.

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 six fully described optional filters and no output schema, the description supplies adequate domain meaning and endpoint context. It lacks sibling-routing guidance, but the schema and readOnlyHint annotation cover most operational needs.

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 every parameter documented in the input schema. The description adds no parameter-specific detail such as filtering syntax or defaults, so the baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource: 'List appeals', and adds useful domain context that appeals are asks such as a year-end letter or gala invitation. It does not distinguish this tool from sibling list tools like bloomerang_list_campaigns or bloomerang_list_funds, which keeps it from 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 does not say when to use this tool versus alternatives, nor does it give prerequisites or exclusions. 'List appeals' and the endpoint reference imply a read operation, but there is no explicit selection 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, so the safety profile is covered. The description adds that goals and dates are included in the response, and the API endpoint hints at the backing operation, but says nothing about pagination behavior, default ordering, or rate limits. This is adequate given the annotation covers safety.

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 endpoint reference is marginal value but cheap. 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?

Seven optional parameters, no output schema, and no guidance on filtering semantics or result shape. The description should at least note that results are paginated and how to combine filters, or what a campaign record contains. For a list tool with this much optional surface, it is under-described.

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

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

Schema description coverage is 100%, so all seven parameters (ids, skip, take, search, has_goal, is_active, last_modified) are already documented with defaults and formats. The description adds no parameter detail beyond what the schema provides. 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 (fundraising campaigns) with the returned fields (goals and dates). It is distinguishable from siblings like list_appeals and list_funds by the campaign resource. Sibling differentiation is implicit rather than explicit.

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 exclusions. The agent must infer that this is the tool for enumerating campaigns. Nothing routes the agent to list_appeals or list_funds when the resource is ambiguous.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the returned content shape (paired roles on each side) and the underlying REST endpoint, but says nothing about pagination behavior, result ordering, or what an empty relationship set looks like — relevant since skip/take exist.

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 returned data and followed by the endpoint mapping. Every clause earns its place; the API route reference is mildly redundant but useful for routing.

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 endpoint with full schema coverage, readOnlyHint, and no output schema, the description covers the essentials: what is returned and for which constituent. It would be stronger with a note on paging defaults or relationship-type filtering, but nothing required to call it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters (constituent_id, skip, take, last_modified) are already documented in the schema. The description only implies the constituent_id via 'this constituent' and adds no filtering or pagination semantics 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 the resource precisely — relationships between the identified constituent and others — and enumerates example roles (spouse, employer, board member), so an agent knows exactly what data comes back. It never says 'list' explicitly in prose and does not contrast itself with siblings like bloomerang_get_constituent, so it stops short of top marks.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as bloomerang_get_constituent or bloomerang_get_constituent_timeline. The usage is only inferable from the resource named, which is minimal for a tool sitting among 19 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 safe-read profile is covered. The description adds that this is a GET endpoint and hints at the incremental-sync pattern, but says nothing about pagination behavior, the 50-record cap, or result shape beyond what the schema already states.

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 the filter enumeration front-loaded and the sync use case last. The endpoint reference is arguably redundant given the tool name, but the description carries 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 10-parameter, zero-required list tool with no output schema, the description covers the filter space and a motivating scenario, and pagination/limit details live in the schema. It is adequate to call the tool correctly, though a note on how results are paginated or capped would have closed the remaining gap.

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

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

Schema description coverage is 80%, so most parameters are already documented (ids, skip, take, is_favorite, last_modified, custom_field_id/value). The description's filter list (Id, type, favorites, last-modified, custom field) largely restates those and lumps sorting into one phrase, adding little 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+resource ('List constituents') and enumerates the filter dimensions it supports, plus names the underlying endpoint (GET /constituents). It does not explicitly distinguish itself from the sibling bloomerang_search_constituents, so an agent still has to infer which listing-style tool to pick.

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?

Offers one concrete usage hint ('Good for syncing recent changes') that implies the last_modified filter, but gives no when-not guidance and never mentions bloomerang_search_constituents or bloomerang_get_constituent as alternatives. Usage is implied rather than specified.

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 is a safe read, and the 'GET /funds' endpoint restates that. The description adds no further behavioral detail such as pagination behavior (which matters given skip/take) or rate limits, but the annotation bar is low here.

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 clauses, front-loaded with the purpose and backed by a concrete example and the underlying endpoint. Zero 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?

A simple read-only list tool with fully documented parameters and an annotation covering safety; the description's remaining gap is return shape, but the absence of an output schema is a minor omission for a straightforward listing call.

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

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

Schema description coverage is 100%, so all six filter parameters (ids, skip, take, search, is_active, is_default) are already fully documented in the schema. The description contributes nothing beyond that, so baseline 3 applies.

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

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

States a specific verb (List) and resource (funds) and adds domain context with examples ('General Operating, Scholarship'), so an agent knows these are designation categories for gifts. It is distinct from siblings like list_campaigns or list_appeals, though it never explicitly contrasts with them.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives. The agent gets no signal about when this is the right call versus other list tools.

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-only nature is covered. The description adds the underlying endpoint (GET /interactions) and the filter dimensions, but says nothing about pagination behavior, result limits, or default ordering that isn't already in 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?

One compact sentence plus an endpoint tag; the core purpose and filter scope are front-loaded with no filler. The trailing API-endpoint note is mildly redundant but not harmful.

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 a fully documented schema and no output schema, the description covers purpose and filterable axes adequately. The main omission is any hint about pagination defaults (skip/take), though the schema already carries those.

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 8 parameters are already documented, including enums for channels and purposes. The description's mention of constituent/channel/purpose filtering maps to existing schema fields but adds no syntax, default, or format detail beyond them — 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 (logged interactions) with concrete examples of what an interaction is (calls, emails, meetings, letters) and names the filterable dimensions. It is clearly distinguishable from sibling create_interaction and list_notes, though it does not explicitly contrast itself with them.

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

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

Usage is only implied by the mention of filters — an agent can infer this is for retrieving/browsing interactions, but there is no explicit when-to-use guidance, no exclusions, and no pointer to alternatives like get_constituent_timeline or search_constituents for other retrieval needs.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the Bloomerang endpoint (GET /notes) and optional constituent filtering, but does not disclose pagination behavior, rate limits, or return shape. With annotations present, this is adequate but not rich.

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

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

Two short sentences, front-loaded with the core purpose. The second sentence adds endpoint context without waste. No filler or repetition of schema details.

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 parameter schema and readOnlyHint annotation, the description is minimally sufficient for selecting and invoking the tool. However, with no output schema, it does not describe return values or pagination behavior, leaving some contextual gaps for a list endpoint.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description only implies constituent filtering via 'optionally for specific constituents,' which the schema already states. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'List notes, optionally for specific constituents.' This clearly distinguishes it from siblings such as bloomerang_create_note and bloomerang_list_interactions. The added Bloomerang endpoint reinforces the read 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 gives no when-to-use guidance, no exclusions, and no alternatives. 'Optionally for specific constituents' is a filter hint, not usage guidance. An agent must infer that this tool is for retrieving notes rather than creating or filtering by other criteria.

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

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

The readOnlyHint annotation already establishes that this is a safe, non-mutating read. The description adds the REST mapping (GET /tasks) and lists filter dimensions, but says nothing about pagination behavior, result caps (take max 50), or ordering defaults, so it adds only modest context beyond the annotation.

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

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

Two compact sentences: the capability and filter list come first, the endpoint reference last. No filler, no redundancy.

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

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

For a 12-parameter, zero-required list tool with no output schema and minimal annotations, the description covers filtering but not paging (skip/take limits) or how results are ordered/returned. It is adequate but leaves the agent to mine the schema for paging behavior.

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

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

Schema description coverage is 75%, so most parameters are already documented in the schema. The description echoes six filter dimensions (status, due-date range, assignee, constituent, channel, purpose) that largely duplicate existing schema descriptions and omits paging/ordering params, adding no new semantics. 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 gives a specific verb+resource ('List tasks (follow-ups)') and enumerates the filterable dimensions, so an agent immediately knows this is a read/list operation over tasks. It is clearly distinct from the sibling bloomerang_create_task, but it never names or differentiates itself from other list tools, which caps it at 4.

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 text implies when to use it (retrieving tasks, optionally narrowed by status, dates, assignee, constituent, channel or purpose) but gives no explicit when-not conditions or alternative tools. Usage context is inferable rather than stated.

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

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

The only behavioral claim is 'Read only,' which merely restates the readOnlyHint=true annotation already present, so it adds no new information. The GET /transactions endpoint mapping is mildly useful context, but the description says nothing about pagination limits, default sort behavior, or result envelope.

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

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

One tight sentence with the core purpose front-loaded, followed by short filter and endpoint notes. Slightly padded by the redundant 'Read only' clause that duplicates annotations, but overall 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 an 11-parameter list tool with no output schema and only a readOnlyHint annotation, the description is adequate but leaves gaps an agent would want: pagination behavior (take max 50, skip), default ordering, and whether results include designation detail. Coverage of the filter surface compensates partially.

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 fully documents all 11 parameters — the baseline is 3. The description's filter mentions (constituent, amount range, type, last-modified) loosely map to parameters but add no syntax, defaults, or semantics beyond what the schema already provides.

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 (transactions/gifts) and enumerates the subtypes covered — donations, pledges, pledge payments, recurring donations — plus the associated designations. This clearly separates it from the sibling bloomerang_get_transaction (single record) and from the create_* write 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?

It lists the available filter axes (constituent, amount range, type, last-modified date), which implies when the tool is useful, but gives no explicit when-to-use/when-not guidance or named alternative for retrieving a single gift. Usage is inferable rather than stated.

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

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

The readOnlyHint annotation already establishes this is a safe read operation, and the description adds that it is full-text and which entities/fields are covered plus the underlying endpoint. It does not disclose result caps (take max 50), ordering, or result shape, so it adds moderate context beyond annotations but not rich behavioral 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?

Two tight sentences front-load the core capability followed by the workflow hint and endpoint reference. Every clause carries signal, though the trailing 'Bloomerang: GET /constituents/search' is marginally redundant 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 read-only search with a fully documented schema and no output schema, the description covers purpose, scope, and the downstream workflow sufficiently. Minor gaps around pagination behavior and result ordering remain but are largely carried by 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 all four parameters (search, type enum, skip, take) are already documented in the schema. The description adds no syntax, matching behavior, or example values beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb+resource ('full-text search across constituents') and enumerates the entity types (individuals, organizations, households) and searchable fields (name, email). It implies a distinction from list_constituents by emphasizing full-text search, but never names that sibling explicitly, so the differentiation is left to inference.

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 useful workflow cue (a search-then-get flow), implying this precedes bloomerang_get_constituent. However it offers no explicit when-not-to-use guidance or contrast with bloomerang_list_constituents for browsing, so usage is only implied.

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

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

The 'WRITE:' prefix is consistent with destructiveHint=true, and the description adds genuinely useful behavior beyond the annotation: 'Only the fields you supply are sent' discloses partial-update semantics, and the PUT /constituent/{id} endpoint is given. It still omits permission needs and what happens to omitted or invalid values.

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 WRITE classification, the verb/resource, then the partial-update rule and endpoint. No filler; every clause conveys actionable 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 20-parameter, nested-object mutation tool with no output schema and minimal annotations, the description covers the essentials (what it mutates, patch semantics, endpoint) but leaves much parameter-level and outcome-level detail undocumented. Adequate but with visible 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?

With 20 parameters at only 45% schema description coverage, the description must carry more weight, and it only groups fields generically (names, job, status, primary address/email/phone). Many parameters (gender, website, employer, birthdate, recognition_name) get no added meaning in either place, so it partially but not fully compensates.

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 ('update fields on an existing constituent's profile') plus the field groups touched, and the word 'existing' separates it from bloomerang_create_constituent. It stops short of naming a sibling alternative outright, so it is clear but not fully differentiated by reference.

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

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

Usage is only implied: an agent infers this is the tool for modifying an already-created constituent. There is no explicit when-to-use/when-not, no statement that create should be used for new records, and no prerequisites (permissions, whether the record must exist).

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