Virtuous MCP by usefulapi

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

Annotations only declare destructiveHint=true and a title, so the description must carry behavioral weight and partly does: the POST endpoint and the 'existing tag' constraint tell the agent this is a write that will fail for unknown tags. It does not explain idempotency, duplicate-tag behavior, or permission requirements.

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

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

A single front-loaded sentence plus a compact endpoint tag; nothing is wasted and the prerequisite lookup is stated inline. Slightly terse, but appropriately sized for a two-parameter mutation.

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

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

For a simple two-param write with no output schema, the description covers the essentials of invocation. It leaves the agent guessing about the outcome (created vs. duplicate) and any auth/permission context that a destructiveHint alone doesn't convey.

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

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

Schema coverage is 100%, so both parameters are documented as integers with positivity bounds. The description adds only that tag_id must be sourced from virtuous_list_tags; no format or edge-case 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 specific verb+resource: applying an existing tag to a contact, and notes the tag must already exist. It also distinguishes itself from lookup siblings by pointing to virtuous_list_tags, though it doesn't compare against list_contact_tags.

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 (tag a contact) and it gives a useful prerequisite pointer to virtuous_list_tags for the tagId. There is no explicit when-not guidance, e.g. what to do if the contact already has the tag, or whether list_contact_tags should be checked first.

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

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

The annotations already carry destructiveHint=true, and the description usefully confirms the mutation by stating 'Writes to the donor record' and naming the POST endpoint. It adds no further behavioral context such as permission requirements, whether the note can be edited/deleted afterward, or side effects on the contact's record.

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 filler; the purpose is front-loaded before the endpoint detail, and nothing is repeated from 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 simple create tool with full schema coverage and an existing destructiveHint annotation, the description covers purpose and the fact that it writes. However, with no output schema, it says nothing about what is returned (e.g., a new note id), and gives no error or validation context, leaving a small completeness gap.

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

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

Schema description coverage is 100%, so note, type, private, important, contact_id, time_spent and note_date_time are all fully documented in the schema. The description adds nothing about parameter semantics, which is acceptable at baseline 3 given 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 specific verb and resource ('Add a note to a contact's timeline') plus concrete examples of what a note covers (call, meeting, visit, touchpoint), and names the backing endpoint. This clearly distinguishes it from read-only siblings like virtuous_list_contact_notes or unrelated writes like virtuous_create_gift_transaction.

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 examples of touchpoints, which help an agent recognize the right scenario, but there is no explicit when-to-use/when-not guidance and no mention of the sibling alternatives (e.g., using list_contact_notes to read back notes). Nothing is misleading, but 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?

Goes well past the destructiveHint annotation by disclosing the full lifecycle: dedup matching against existing contacts by name/email/phone/address/reference, batching into an import at midnight, and commit only when a user reviews and clicks Run. The 'nothing is created in real time and no duplicates are forced' note is exactly the kind of consequence an agent needs before submitting.

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

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

Front-loads the verb, resource, and recommendation, then uses the rest for genuinely load-bearing behavior (batching, midnight, manual commit). The middle sentence is dense with several dash-separated clauses and the trailing API path is low-value padding, but nothing is truly 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 23-param, zero-required, deferred-commit tool with no output schema, the description covers the critical unknown: what happens after submission and when data actually lands. It omits any guidance on minimum identifying fields needed and what the call returns, but those are moderate gaps given the annotations carry the safety profile.

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 only 48% schema coverage across 23 params, the description compensates by naming the fields that drive dedup matching (name, email, phone, address, reference), which explains why those parameters matter rather than just what they accept. It still leaves many address/name-component params (city, postal, suffix, address1/2, etc.) without added semantics.

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 ('Submit a new or updated contact') plus the mechanism (Virtuous's import pipeline), and explicitly positions it as 'the recommended way to add contacts' versus the read/side-effect siblings like search_contacts or add_contact_tag. An agent can identify its role without opening the schema.

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

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

Gives clear context for when to reach for it (adding or updating contacts, the recommended path) and implicitly what not to expect (no real-time creation). It does not name an alternative tool or state exclusions, so it stops short of explicit routing.

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

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

Goes well beyond the lone destructiveHint annotation by disclosing the deferred, two-phase lifecycle: the gift is matched to a contact/recurring gift/pledge, held until the nightly import, and only created after a human reviews and clicks Run. That is exactly the kind of non-obvious side-effect timing an agent needs before calling a 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?

Four dense sentences, front-loaded with purpose, then behavior, then donor identification, then the upstream endpoint. No filler; the endpoint reference at the end is terse and contextual rather than padding.

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

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

For a 17-parameter, nested-object tool with no output schema, it covers the essentials: what gets created, when, what does not happen (no charge), and how the donor is identified. It doesn't touch the deferred-import failure/preview mechanics or how designations and recurring frequency interact with contact matching, but the safety and lifecycle essentials are present.

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 71%, so the schema already carries much of the load, but the description adds real value by explaining the three donor-identification strategies (contact.id, contact.referenceId, or name/email details) and the contact-matching behavior, which is not stated in the schema. It doesn't clarify attribution/designation or dedup semantics beyond what the schema 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+resource ("Record a gift... through Virtuous's gift import pipeline") and scopes it precisely enough to distinguish it from sibling read tools like virtuous_get_gift and from the separate virtuous_create_contact_transaction path. The parenthetical "donation already received" removes ambiguity about whether money is being moved.

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 clear context ("the method Virtuous recommends") and an important negative exclusion ("it does NOT charge anyone"), which steers the agent correctly. It stops short of explicitly naming the alternative path — e.g. when to prefer virtual_create_contact_transaction over this import pipeline — so the routing 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.

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 a genuine behavioral rule beyond the schema: when both identifiers are supplied, Virtuous prioritises the reference. It does not disclose not-found behavior or the shape of the returned contact.

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 an endpoint reference, with the primary use case front-loaded and no filler. Every clause carries operational 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 and an empty required-parameter list, the description usefully compensates by specifying the valid parameter combinations. What an agent still cannot infer is the failure mode when neither identifier matches a contact.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the either/or requirement between email and the reference pair, and the precedence rule when both are provided. That cross-field logic is not expressible in the flat property descriptions.

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 ('Look up a single contact') and names the two lookup keys, which distinguishes it from bulk siblings like virtuous_search_contacts. It never names a sibling explicitly, 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?

Gives an explicit invocation rule: supply either email, or both reference_source and reference_id, with reference taking precedence when both are present. It does not say when to prefer this over virtuous_search_contacts or virtuous_get_contact, so no exclusions or alternative routing are offered.

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 as a safe read, but the description adds real value beyond it by disclosing the shape of the returned record (giving summary, individuals, contact methods, custom fields). With no output schema present, this return-content disclosure is what lets an agent plan follow-up calls. It still omits error behavior for an invalid/nonexistent ID and any authorization or rate-limit constraints.

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 dense but well-front-loaded sentence covers purpose plus payload, followed by a short API endpoint reference. Nothing is padded or redundant, and the core action is stated first.

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, no-output-schema read tool, the description covers what comes back and effectively implies the ID-based lookup workflow, which is enough for correct invocation. Missing only failure-mode and permission context, which are secondary here.

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

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

Schema description coverage is 100% and the single parameter (contact_id, integer > 0) is fully documented in the schema, so the baseline is 3. The description adds no extra semantics such as ID sourcing or format beyond the schema's own constraint.

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 contact), and enumerates the payload contents: address, giving summary (life-to-date, YTD, last gift), individuals and contact methods, and custom fields. The singular 'one contact' implicitly separates it from the search/list siblings, but it never names an alternative such as virtuous_find_contact or virtuous_search_contacts to make that distinction 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?

Usage is only implied: the required contact_id and the single-record wording suggest 'call this when you already have one contact's ID.' There is no stated when-not-to-use, no guidance on how to obtain the ID (e.g. via virtuous_search_contacts), and no mention of behavior when the ID does not exist.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real value on top by labeling the call 'cheap' and positioning it as a connectivity/credential probe. It does not describe failure behavior on an invalid key, which is the one behaviorally interesting case for a health-check 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?

Two sentences, front-loaded with the resource and scope, followed by the practical shortcut value. The endpoint reference ('Virtuous: GET /api/Organization/Current') is a compact traceability aid rather than 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 carries the burden of describing the return and does so in part by listing name, time zone, culture, and the administrator flag. That covers the essentials for a zero-parameter read, though it is a summary rather than an exhaustive field list.

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 no argument surface for the description to clarify. The baseline for a parameterless tool is 4, and nothing in the description misleads about inputs.

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

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

Names a specific verb and resource ('Fetch the Virtuous organization this API key acts in') and goes further by enumerating the returned fields (name, time zone, culture, admin flag). The sibling list is dominated by contact/gift operations, so this stands apart with no risk of confusion.

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

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

Gives a concrete usage context: 'A cheap way to confirm the key works,' which tells the agent when to reach for it (credential/health check). It stops short of naming exclusion conditions or an alternative, but there is no plausible sibling that competes for the same job.

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 non-mutating read, so the bar is lower. The description adds the return-content scope (designations, premiums, custom fields), but says nothing about error behavior for a missing gift id, authentication requirements, or rate limits.

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

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

Two compact sentences, with the verb and scope front-loaded and the endpoint reference trailing as a cheap supplementary cue. The long field enumeration earns its place only because no output schema exists, but it does make the sentence dense.

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 field enumeration is the only source of return-shape information, and it covers contact, amount/currency, batch, segment, designations and custom fields thoroughly. The remaining gap is the absence of any error/not-found behavior for an invalid gift id.

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

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

Schema description coverage is 100% and gift_id is documented as a positive integer in the schema itself, so the baseline of 3 applies. The description adds no format, range, or lookup-hint meaning beyond what the schema already states.

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

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

The description states a specific verb and resource ('Fetch one gift') and enumerates the fields returned, so the agent knows exactly what record shape comes back. It is distinguishable from the listing sibling (virtuous_list_contact_gifts) by the singular 'one gift in full', but it never names that sibling explicitly, so it stops short of a 5.

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

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

Usage is only implied: 'Fetch one gift in full' suggests retrieving the complete detail record for a known gift id, contrasted with the list_contact_gifts sibling. There is no explicit when-to-use, when-not-to-use, or prerequisite statement, leaving the agent to infer the decision rule.

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, non-mutating read, so the description's main added value is the field inventory it returns (compensating for the absent output schema). It says nothing about auth requirements, error behavior for a missing/invalid id, or rate limits.

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

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

Two front-loaded sentences with no filler: the purpose and returned fields come first, the underlying API call last. The long field enumeration is dense but earns its place as the only description of the response shape.

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

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

For a simple single-record getter with one fully documented parameter and readOnly annotations, the description covers what is needed, and the field list compensates for the missing output schema. Only the lack of alternative routing to search_projects keeps it short of complete.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema fully documents project_id (integer, >0). The description adds no format or semantics beyond echoing {projectId} in the endpoint path, which is the correct baseline 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?

States a specific verb and resource ('Fetch one project') and enumerates exactly what the record contains, so the agent knows this returns a single full project object. It implicitly contrasts with the sibling search_projects/list tools by saying 'one project', though it never names the alternative openly.

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, when-not-to-use, or alternative routing. The only usage signal is the implicit single-record scope from 'Fetch one project' and the required project_id. An agent must infer that search_projects is the route when the id is unknown.

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 declare readOnlyHint=true, so the description carries additional weight and delivers it: it discloses the return content (parameter names, types, allowed operators, value options) and cites the raw API endpoint. It stops short of format/volume details, but adds real context beyond the annotations.

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

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

Three short sentences, front-loaded with the purpose, then the usage directive, then the API anchor. No filler and every clause is informative.

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

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

There is no output schema, so the description must describe returns — and it does, enumerating parameters, types, operators and value options. For a one-param discovery tool, nothing an agent needs 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% with a single enum-constrained 'resource' param, so the schema already documents the input. The description adds only 'for one record type', which loosely clarifies the param's meaning without new syntax 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 (List) and resource (parameters, types, operators, value options), and explicitly names the sibling it feeds into (virtuous_query). An agent can distinguish it from the search/query/list siblings 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?

Explicitly instructs 'Call this BEFORE building a query', which routes the agent relative to the virtuous_query sibling. It lacks an explicit when-not or alternative branch, but the sequencing guidance is clear.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the returned field set and the underlying endpoint, which is useful, but says nothing about pagination behavior or result sizing despite the schema exposing skip/take. 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 sentences, zero waste. The primary action and returned payload are front-loaded, then the alternative tool and endpoint follow. 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?

With no output schema, the description usefully compensates by listing the shape of each returned gift row, and the sibling routing closes the main ambiguity. Only pagination/sorting behavior is left entirely to 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 skip, take, sort_by, descending and contact_id are all documented in the schema already. The description adds no parameter-level syntax or defaults, which is acceptable given full schema coverage.

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

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

States a specific verb and resource (list a contact's giving history) and enumerates the returned fields (gift id, type, date, amount, segment, batch). It explicitly differentiates itself from the sibling virtuous_get_gift, which handles designations and full detail.

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?

Names the alternative (virtuous_get_gift) and the condition that selects it ('for designations and full detail'). There is no explicit when-not guidance (e.g., how it relates to the gift list embedded in search tools), but the routing instruction 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?

The readOnlyHint annotation already establishes the safe read-only nature, so the description is not burdened with safety disclosure. It usefully adds the returned fields (names, birth dates, emails, phones) and the underlying API endpoint, going beyond the annotation. It omits pagination behavior, but for a simple list tool this is acceptable.

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, front-loaded with the tool's purpose, followed by a compact API endpoint reference. There is no wasted verbiage and the structure is immediately scannable.

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

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

For a simple one-parameter list tool with no output schema, the description supplies the essential purpose, returned fields, and endpoint. It could mention pagination or behavior on invalid IDs, but the core needs are covered.

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 parameter `contact_id` is fully documented in the schema. The description adds no extra syntax or format details, which matches the baseline of 3 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 (list) and resource (individuals belonging to a contact/household), and enumerates the returned fields. It is clearly distinct from siblings that list gifts, notes, tags, or search contacts, though it does not explicitly name those alternatives.

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

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

The description provides no when-to-use guidance, prerequisites, or alternatives. It implies the tool's purpose but offers no indication of when to choose it over `virtuous_get_contact` or `virtuous_search_contacts`.

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 real value by naming the returned content (calls, meetings, emails, touchpoints with type, date, text, author), but says nothing about pagination limits, default page size, or auth requirements, all of which matter for a listing call.

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: the first defines the resource and payload, the second pins the exact upstream endpoint. No filler or restated 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 usefully enumerates the fields returned, and the endpoint reference removes ambiguity about which API surface it hits. Only the paging/ordering behavior of the list is unaddressed, which the schema partly covers.

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 skip/take/sort_by/descending all documented in the schema, so the schema carries parameter semantics. The description adds nothing about the cursor-style skip/take paging or the enum sort fields, so baseline 3 applies.

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

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

States a specific verb and resource with scope: 'List the notes logged on a contact', and enumerates the returned fields (type, date, text, author). An agent can distinguish it from the write-side sibling virtuous_create_contact_note. It does not explicitly name any sibling it could be confused with, so it stops short of 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 gives no when-to-use, when-not-to-use, or alternative tool guidance; it never mentions virtuous_create_contact_note or any search/list sibling. Usage is only inferable from the fact that the tool takes a contact id.

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=true annotation already tells the agent this is a safe, non-mutating read, lowering the descriptive burden. The description adds the underlying API endpoint (GET /api/ContactTag/ByContact/{contactId}) and partial return fields, but says nothing about pagination defaults, ordering, or error behavior beyond what the schema supplies.

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 no filler: the purpose plus return fields come first, and the API endpoint reference follows. Nothing is redundant or misplaced.

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 annotations covering safety, full schema coverage, and no output schema, the definition supplies the resource, the returned fields, and the endpoint. It is essentially complete; only pagination/ordering behavior is left unmentioned, and the schema already documents skip/take.

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

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

Schema description coverage is 100%, so skip, take, and contact_id are already documented in the schema (including the 1-100 and default constraints). The description only restates contactId via the path template and adds no new parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the tags applied to a contact') and even enumerates the returned fields (contactTagId, tagId, name). This implicitly separates it from the sibling virtuous_list_tags (all tags) and virtuous_add_contact_tag, though it never names those alternatives explicitly.

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

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

The scoping phrase 'applied to a contact' and the path template imply the tool is used when you already have a contact id and want its tags, which is reasonable inferred guidance. However, there is no explicit when-to-use statement, no when-not-to-use, and no routing to sibling tools like virtuous_list_tags or virtuous_add_contact_tag.

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?

Annotation already declares readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint and the field set, which partially compensates for the absent output schema, but says nothing about ordering, default page size semantics beyond the schema, or rate limits.

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

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

Two short sentences that are front-loaded with the actionable field list; nothing is redundant. The trailing 'Virtuous: GET /api/Event' is marginally useful metadata but not essential to the 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?

With no output schema, enumerating returned fields is exactly the right compensation, and skip/take are fully covered by the schema plus readOnlyHint. Only pagination/ordering behavior and explicit usage context are 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% and both parameters (skip, take with bounds and defaults) are fully documented in the schema. The description adds no meaning beyond that, 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?

Specific verb ('List') plus resource ('the organization's events'), and the description enumerates the exact fields returned (name, type, location, dates, invite/RSVP counts, attendance, giving). No sibling in the list overlaps this resource, so an agent can route to it unambiguously.

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 statement, no prerequisites, and no reference to alternatives (e.g., virtuous_query or search tools that might also surface events). Usage is only implied by the verb 'List'.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value with annotations present: it discloses the shape of returned records (id, name, tag group) and the underlying endpoint GET /api/Tag, which helps an agent plan the follow-up call. It stops short of mentioning pagination behavior, though the schema covers 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?

Three short sentences with zero filler: the purpose and return fields come first, then the workflow hint, then the API reference. Nothing is redundant against the structured fields.

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

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

With no output schema, the description usefully names the return fields, and the annotations carry the read-only safety profile. For a simple 2-param, zero-required list tool this is essentially complete; only an explicit disambiguation from virtuous_list_contact_tags is missing.

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

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

Schema description coverage is 100%, with skip and take both documented including defaults and bounds, so the schema does the heavy lifting. The description adds nothing about pagination semantics beyond what the schema states, which is the expected baseline-3 outcome.

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+resource ('List the organization's tags') with the returned fields named parenthetically (id, name, tag group). It does not explicitly distinguish itself from the closely-named sibling virtuous_list_contact_tags, so an agent could still conflate the two without opening schemas.

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 states the use case and downstream consumer: 'Use this to find a tagId before virtuous_add_contact_tag.' That is clear context, but it gives no exclusion against the other tag-related sibling (virtuous_list_contact_tags) and no filtering 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?

readOnlyHint=true already covers the safety profile, and notably the description does not contradict it despite the underlying POST (a query POST is still a read). The description adds real behavioral context beyond the annotations: the return envelope { list, total } and the fact that full_details switches Contact/Gift queries to full records rather than the abbreviated view. It does not mention rate limits or pagination cost, which keeps it short of a 5.

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

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

Four tight sentences with no filler; the scope of the tool is front-loaded before the conditions/return details and the API mapping trails at the end. Everything present is relevant, though the endpoint line (POST /api/<Resource>/Query) is the most expendable element.

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 query tool with no output schema, the description supplies the missing return shape ({ list, total }) and the full_details behavior switch, so an agent can interpret the response without one. The main gap is sibling positioning versus the extensive list_*/search_* family, which is the most likely source of wrong-tool selection.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not carry: it points conditions at virtuous_get_query_options as the authoritative source of valid parameter/operator names, which is the single hardest thing to get right when calling this tool. The full_details note largely restates the schema description ('Contact and Gift only'), but the cross-tool reference is a genuine addition.

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: runs a Virtuous query-builder query against one record type, and enumerates the record types (contacts, gifts, campaigns, projects, tasks, grants, pledges, recurring gifts, events). It also gives the concrete API mapping (POST /api/<Resource>/Query). However, it never distinguishes this generic query tool from the many per-resource siblings (virtuous_list_contact_gifts, virtuous_search_contacts, etc.), so an agent cannot tell from the description alone why it would pick this over a specialized list/search 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?

The description supplies one real workflow prerequisite: condition parameter/operator names must come from virtuous_get_query_options. That is useful routing, but there is no explicit when-to-use guidance and no when-not-to-use or named alternative against virtuous_search, virtuous_search_contacts, or the numerous list_* siblings. Usage is only implied by 'run a query-builder query'.

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. The description adds useful behavior beyond annotations: hits include highlights and are grouped by kind, and it gives the underlying HTTP mapping (POST /api/Search). It doesn't mention pagination behavior beyond the schema, but the added result-shape detail is real 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?

Three compact clauses: scope, result shape, and endpoint. Front-loaded with purpose and no filler sentences.

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

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

Covers scope, result grouping, and the API mapping. For a read-only, well-annotated search with a fully documented schema and no output schema, the main remaining gap is routing guidance versus narrower sibling search tools.

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

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

Schema coverage is 100%, so skip, take, query, and filter_types are all documented in the schema. The description adds no parameter-level detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb (search) and resource scope (contacts, individuals, entities), and explicitly frames it as the global search bar equivalent. It is distinguishable from narrower siblings like virtuous_search_contacts and virtuous_search_projects by its breadth, though it doesn't explicitly name 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?

Implies usage ('the same search as the Virtuous search bar', 'grouped by kind') but never states when to prefer this over the narrower search_contacts or search_projects siblings, nor any exclusions. An agent must infer that this is the cross-cutting option.

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 safety profile, so the bar is lower. The description adds genuine context beyond the annotations: it discloses that matching is 'fully or partially' (substring/LIKE semantics) and enumerates the fields returned per match, which helps the agent reason about result shape.

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 that front-load the query semantics and then the return fields. The trailing 'Virtuous: POST /api/Contact/Search' is slightly noisy for an agent but is short and grounded in the real endpoint.

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, three-parameter search with full schema coverage and no output schema, the description covers purpose, matching semantics, and returned fields. The main gap is sibling differentiation and pagination behavior, which the skip/take params partly cover.

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 (search, skip, take) are already documented, including defaults and ranges. The description only adds that the search string matches against multiple fields, which is mild added meaning; 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 states a specific verb and resource ('Find contacts') and enumerates the matched fields (name, email, phone, address), which is more informative than the title alone. However, it never distinguishes itself from close siblings like virtuous_find_contact or virtuous_search, so an agent cannot confidently route between them from this text.

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, no exclusions, and no named alternative despite several overlapping siblings (virtuous_find_contact, virtuous_search, virtuous_query). The partial-match behavior implies a lookup scenario but the agent must infer when this tool 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 description's added value is the disclosure of what comes back (balances, financial need, life-to-date giving). It adds no pagination, rate-limit, or ordering context beyond what the schema provides, which is acceptable 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 tight sentences; the purpose and the returned fields are front-loaded before the trailing endpoint note. The 'Virtuous: POST /api/Project/Search' fragment is mildly extraneous but negligible in size.

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

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

With no output schema, the description usefully enumerates the key return fields, and all three parameters are schema-documented with the read-only safety profile covered by annotations. An agent has enough to call it correctly; only the search-vs-get routing remains unaddressed.

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

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

Schema description coverage is 100%, so skip/take/search are fully documented in the schema and the baseline is 3. The description's 'by name or code' merely restates the schema's own 'match against project name or code' clause and adds no syntax or format guidance.

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 ('Find projects') and even disambiguates the domain term by glossing a project as 'funds / designations gifts are given to', plus states the payload fields returned. It stops short of distinguishing itself from the sibling virtuous_get_project, which an agent would also need to choose between.

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: 'Find ... by name or code' signals a text-lookup intent, but the description never states when to search versus calling virtuous_get_project, nor any prerequisites. No exclusions or alternatives are named, so the agent must infer the split.

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