virtuous-crm

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

The annotations already declare destructiveHint=true, and 'Apply' restates only that this is a write. The description adds no behavioral detail beyond what annotations provide: no mention of duplicate/already-applied tag behavior, idempotency, or whether re-tagging silently succeeds. The only extra is the raw endpoint reference, which adds little for an agent.

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 short sentence with the action front-loaded, plus a parenthetical prerequisite. Every clause earns its place; 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 two-parameter mutation with a fully documented schema, destructiveHint present, and no output schema to explain, the description covers the essentials. The remaining gap is behavioral: what happens on repeated tagging is left unstated.

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 both tag_id and contact_id documented in the schema, so the baseline is 3. The description adds the provenance of tagId (from virtuous_list_tags), a marginal but real gain over the schema alone.

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: 'Apply an existing tag to a contact.' It also names the sibling used to obtain the tagId (virtuous_list_tags), implicitly separating lookup from application. The only deduction is that it does not explicitly contrast with other tag-related siblings such as 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?

It gives a concrete prerequisite and routing hint — obtain the tagId via virtuous_list_tags first — which is exactly the guidance an agent needs to avoid a failed call. There is no when-not-to-use or handling for tags that are already applied, so it stops just short of a 5.

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

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

Annotations already declare destructiveHint=true, and the description reinforces the write nature with 'Writes to the donor record' plus the POST endpoint. However, it does not explain what the destructive hint means in practice for an additive note, nor mention permissions, validation against contact_id, or effects on the contact record. With annotations covering the safety profile, this is adequate but thin.

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 and usefully capped by the underlying API mapping (POST /api/ContactNote). Nearly zero waste; the endpoint line is the only mildly implementation-flavored sentence, but it is genuinely useful for agents mapping to the Virtuous API.

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-parameter creation tool with full schema coverage, no output schema, and one annotation, the description supplies purpose, write semantics, and endpoint mapping. It lacks only failure/prerequisite details (e.g., the referenced contact must exist), which is a minor gap given the schema does the parameter work.

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 (note, type, private, important, contact_id, time_spent, note_date_time) are already documented in the schema. The description adds no parameter-level 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?

States a specific verb and resource — 'Add a note to a contact's timeline' — with concrete examples of what a note represents (call, meeting, visit, touchpoint). The resource is clearly distinct from siblings such as virtuous_add_contact_tag or virtuous_create_contact_transaction, so an agent can route without opening the schema.

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

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

The examples (call, meeting, visit, touchpoint) imply the appropriate use case for logging activity history, but there is no explicit when-to-use/when-not guidance and no alternative named (e.g., use virtuous_list_contact_notes to read notes back). Usage is inferable but not spelled out.

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

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

Despite destructiveHint=true, the description discloses the deferred pipeline mechanics: matching against existing contacts by several keys, batching into a midnight import, and committing only after a user reviews and clicks Run. It explicitly clarifies 'nothing is created in real time and no duplicates are forced', which is exactly the non-obvious behavior an agent needs and is not derivable from 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?

Purpose and recommendation are front-loaded, then the longer clause earns its length by explaining the deferred-commit behavior. It is effectively one dense sentence followed by the endpoint path; slightly run-on but 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?

With no output schema, the description still omits what the submission returns (e.g., an import/transaction identifier). However, for a 23-param mutation tool it explains the async lifecycle thoroughly, so the main gaps are return-value and per-parameter detail rather than core 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 48% (below the 50% threshold), so the description must compensate but largely does not. It only hints that name, email, phone, address and reference are used for matching, leaving the majority of the 23 parameters (city, state, tags, custom_fields, email_type, etc.) with no added meaning.

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

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

The description states a specific verb+resource ('Submit a new or updated contact through Virtuous's import pipeline') and immediately positions it as 'the recommended way to add contacts', which distinguishes it from the read/lookup siblings like find_contact and get_contact. Nothing else in the sibling set performs contact creation, and the pipeline semantics make its role unambiguous.

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

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

It gives clear when-to-use context ('the recommended way to add contacts') and implies the tool handles both new and updated contacts. It stops short of naming an explicit alternative to prefer or a when-not condition, so it is strong but not fully 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?

With only destructiveHint=true in annotations, the description carries most of the behavioral burden and does so well: the gift is matched to a contact/recurring gift/pledge, held until the nightly import, and only created after a user reviews and clicks Run. It also explicitly clarifies 'it does NOT charge anyone', which usefully counters the harsh destructiveHint. Missing auth/permission and idempotency-replay details.

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 core action and pipeline behavior, then closes with the donor-identification hint and the API endpoint. Every sentence is doing work, though the endpoint citation and the redundant title line add little 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 17-parameter, nested-object mutation with no output schema, the description conveys the essential lifecycle (held, reviewed, then created) and donor identification. It leaves gaps on return behavior and on several optional fields (designations, custom_fields, transaction_id), but the schema covers most of those adequately.

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% (mid-range), and the description only adds contact-matching semantics ('identify the donor with contact.id, contact.referenceId, or name/email') that the schema already largely documents. Nothing is said about transaction_id double-import behavior, designations splitting, or currency handling, so it does not compensate for the uncovered parameters.

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 ('Record a gift') plus the exact pipeline used, and the title/sibling set makes clear this is the gift-import path rather than contact/note/tag creation. An agent can distinguish it from virtuous_create_contact_transaction by the import-pipeline framing.

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?

Says this is 'the method Virtuous recommends' and scopes it to a donation already received, which gives a clear context for choosing it. It never names the alternative gift-creation sibling or states when not to use it, so it stops short of full routing guidance.

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

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 behavioral context absent from the schema: that the schema's 0-required-param shape still demands one of two key combinations, and that reference wins over email when both are present.

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-loaded with the lookup semantics and the key-combination rule in two tight sentences; the trailing 'Virtuous: GET /api/Contact/Find' is mildly useful API mapping but not strictly needed for invocation.

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 3-parameter lookup with no output schema, the description covers the key selection logic fully. It does not describe the returned contact shape or the not-found behavior, which matters somewhat given no output schema exists.

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 cannot: the either/or requirement between email and the reference pair, plus the precedence rule when both are supplied. It also illustrates reference_source with concrete providers.

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 (look up) and resource (a single contact) and names the two lookup keys (email vs. reference source + id). The word 'single' distinguishes it from the sibling list/search tools, so an agent can route 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 an explicit invocation rule: supply either email or both reference_source and reference_id, and a tie-break ('Virtuous prioritises the reference'). It does not compare against virtuous_get_contact or virtuous_search_contacts, so the when-to-use-vs-alternative guidance is missing.

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, so the description earns credit by disclosing the return payload (addresses, life-to-date/YTD/last-gift summary, individuals and their contact methods, custom fields). It stops short of noting pagination, latency, or permission requirements, but the return-content disclosure is substantive given no output schema.

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

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

Two sentences, front-loaded with the action and followed by the payload breakdown, with no filler. The field enumeration is dense but each item conveys what the caller receives, so little is wasted.

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

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

With no output schema and a single required parameter, the description is the main carrier of return-value information and it does cover the response shape adequately. The main omission is any guidance on behavior when the contact_id does not exist or is inaccessible.

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% for the single contact_id parameter, so the schema already carries the parameter documentation. The description adds only mild context by naming entity types a contact can represent and citing the API path form, which is the expected 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 contact') and enumerates the categories (household, organization, foundation) and payload contents, so the agent knows this is a single-record read. It does not explicitly contrast itself with virtuous_find_contact or virtuous_search_contacts, so sibling differentiation is left implicit.

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 'Fetch one contact' plus the underlying GET /api/Contact/{contactId} pattern, telling the agent this is the by-id lookup. No explicit when-to-use, when-not-to-use, or alternative tool routing is provided, so the agent must infer that search_contacts/find_contact are for discovery rather than direct retrieval.

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 genuine value on top: it discloses what the call returns (organization name, time zone, culture, and the caller's admin status) and that it is cheap, making it a useful probe. No rate limits or output format details, keeping it below 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?

Three short, front-loaded statements: what it returns, what it is good for, and the underlying endpoint. Every sentence earns its place with no redundancy.

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

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

With no output schema and no parameters, the description carries the full burden of describing the return payload — and it does, listing the exact fields an agent will get back. Nothing needed to invoke 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?

The tool takes zero parameters, so there is no parameter semantics to explain; per the baseline for 0-param tools this scores 4. The description correctly implies no input is required.

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

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

States a precise verb and resource ('Fetch the Virtuous organization this API key acts in') and enumerates the returned fields (name, time zone, culture, admin status). No sibling tool touches organization data, so an agent can select this 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?

Provides a clear usage context — 'A cheap way to confirm the key works' — telling the agent when to reach for it (connectivity/auth validation). It stops short of explicit when-not guidance or named alternatives, but none of the sibling tools overlap with this scope.

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 covers the safety profile, so the description's value-add is the payload disclosure: it enumerates nearly every returned field (contact, amounts, batch, designations, premiums, custom fields). That is genuinely useful behavior context given no output schema, though auth needs and not-found behavior are unstated.

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 front-loaded sentence plus an endpoint reference, with no filler. The long field enumeration is dense but earns its place because no output schema exists to describe the response.

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-param read with no output schema, enumerating the returned fields is exactly the missing context and it is provided. Only minor gaps remain, such as error/not-found behavior, which are not critical for correct invocation.

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?

There is one parameter with 100% schema description coverage, so the schema already documents gift_id as a positive integer. The description adds nothing about the id's origin or format beyond the {giftId} path echo; 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 ('Fetch one gift in full'), and the endpoint mapping (GET /api/Gift/{giftId}) confirms it is a single-record read. This separates it from list-oriented siblings like virtuous_list_contact_gifts and cross-entity ones like virtuous_get_contact.

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 'one gift' plus a required gift_id; the agent can infer this is the detail lookup after a list/search. No explicit when-to-use, when-not, or named alternative (e.g. virtuous_list_contact_gifts) is given.

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 description adds value by disclosing what data comes back (balances, giving history, gift/giver counts) – especially useful since there is no output schema. It omits details like permissions or pagination, but this is a low-risk read.

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

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

Two compact sentences, front-loaded with the verb+resource and followed by the field list and API path. The dense field enumeration earns its place given the missing output schema, though it is slightly list-heavy.

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 annotations covering safety, the description is essentially complete: it names the resource, the input, and enumerates return fields to compensate for the absent output schema. Only the relationship to the project-search sibling is left implicit.

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 project_id parameter is fully documented in the schema, so the baseline of 3 applies. "GET /api/Project/{projectId}" restates the parameter rather than adding format or constraint detail.

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

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

The description opens with a specific verb+resource ("Fetch one project") and enumerates the returned fields, making the tool's scope unambiguous. It contrasts implicitly with the sibling virtuous_search_projects via "one project," though it never names that sibling.

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

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

Usage is implied by "Fetch one project" and the projectId in the endpoint template, so an agent can infer this is the single-record lookup to use when it already has an id. There is no explicit when-to-use vs. when-not, and no mention of the search alternative.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds that this is a GET discovery endpoint and enumerates what the response contains (parameters, types, allowed operators, value options). It stops short of noting pagination, auth requirements, or whether results are cached, so it earns credit but not a perfect score.

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

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

Two short sentences plus an endpoint reference, all front-loaded: the capability first, the imperative usage rule second. No filler and nothing buried.

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, but the description explicitly enumerates what the response returns, which is exactly what an agent needs before constructing a query. Combined with the readOnlyHint annotation and 100% parameter coverage, nothing essential 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 parameter, so the schema already carries the semantics. The phrase 'for one record type' reinforces the mapping but adds no syntax or format detail beyond the schema, making the baseline of 3 appropriate.

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

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

States a specific verb+resource: it lists the parameters, types, operators and value options that virtuous_query accepts, scoped to one record type. This clearly distinguishes it from the sibling virtuous_query, which executes the query rather than describing its shape.

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,' giving an unambiguous ordering rule relative to virtuous_query. The agent knows exactly when this tool is relevant and which sibling it precedes.

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 declare readOnlyHint=true, so the safe-read profile is covered. The description adds the per-gift field shape (useful since there is no output schema) and the underlying endpoint, but says nothing about result volume, pagination behavior beyond the schema defaults, or what an empty result means.

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 field list and the sibling routing are front-loaded, and nothing is redundant. The trailing 'Virtuous: GET /api/Gift/ByContact/{contactId}' is marginal padding for an agent that already has the schema.

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

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

There is no output schema, and the description compensates by enumerating the returned gift fields. All five parameters carry schema descriptions, so the definition covers both the call and the expected payload adequately for a simple list tool.

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

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

Schema description coverage is 100%, so skip, take, sort_by, descending and contact_id are all already documented in the schema. The description adds no parameter-level meaning beyond exposing contactId in the endpoint path, 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?

Specific verb + resource ('List a contact's giving history') with the returned fields enumerated (gift id, type, date, amount, segment, batch). It also names the sibling it is not (virtuous_get_gift), so an agent can distinguish it from the detail-retrieval tool without opening either schema.

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

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

It explicitly routes the agent to virtuous_get_gift for designations and full detail, which is a clear alternative with a condition. It stops short of stating prerequisites (e.g. the contact must exist) or when to prefer the search/query siblings, so it is clear context rather than a complete when/when-not matrix.

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, and the description adds the useful detail that the response carries names, birth dates, and contact methods. It does not disclose pagination, ordering, or behavior for contacts with no individuals, so it adds only modest value 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?

A single dense sentence front-loads the purpose and returned fields, followed by a short endpoint reference. Nothing is wasteful, though the API endpoint adds little for an agent that cannot call it directly.

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 one required param, no nested objects, and no output schema, the description is nearly sufficient: it enumerates the return payload fields, which compensates for the missing output schema, and is consistent with the read-only annotation. Only pagination/ordering behavior is left unexplained.

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

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

Schema description coverage is 100% for the single contact_id parameter, so the schema already carries the semantics. The description reinforces that the id refers to a contact/household but adds no format or constraint 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 (individuals belonging to a contact/household), and enumerates the returned fields (names, birth dates, emails, phones). This clearly distinguishes it from get_contact or list_contact_notes/gifts/tags 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 'belong to a contact/household' scoping, but there is no explicit when-to-use guidance, no statement of when not to use it, and no pointer to alternatives such as get_contact (which may also surface individuals).

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. The description adds returned-field content (type, date, text, author) and the underlying endpoint, but says nothing about result volume, pagination behavior, or ordering defaults despite those being real characteristics of a list 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 sentences, zero filler, with the core purpose front-loaded before the endpoint detail. Every clause carries information.

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

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

With no output schema, the description usefully previews the return shape, and annotations plus the fully documented schema cover safety and parameters. Only the pagination/ordering defaults and result-count behavior are left unstated, a minor gap.

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

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

Schema description coverage is 100%, so skip, take, sort_by, descending and contact_id are all documented in the schema itself. The description mentions only returned attributes, not any parameter, so it adds nothing beyond the schema — 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 (a contact's notes), and enumerates the content returned — calls, meetings, emails and other touchpoints. This clearly separates it from write siblings like virtuous_create_contact_note, though it never names or contrasts a 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as virtuous_get_contact or virtuous_list_contact_gifts. Usage must be inferred entirely from the name and the resource it targets.

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, so the description's burden is lighter. It adds the backing endpoint (GET /api/ContactTag/ByContact/{contactId}) and the shape of returned records, which is useful, but it says nothing about pagination behavior despite skip/take params, or about what an empty result means.

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

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

Two compact sentences, front-loaded with the operation and followed by return fields and endpoint. Little waste; the endpoint reference is marginally extraneous but adds traceability for an API-aware 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 list tool with a fully described schema and no output schema, the description supplies the return field names, which compensates for the absent output schema. Only pagination/default behavior context is missing, which is minor 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%, so skip, take, and contact_id are fully documented in the schema itself. The description adds no parameter syntax or constraints beyond the schema, matching the baseline 3 for a well-documented 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 (List) and resource (tags applied to a contact), and the parenthetical return fields (contactTagId, tagId, name) plus the underlying endpoint make the operation unambiguous. It does not explicitly contrast with siblings like virtuous_list_tags or virtuous_add_contact_tag, but the 'applied to a contact' scoping implicitly distinguishes it.

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 name and description: an agent can infer it should call this when it needs an existing contact's tags. There is no explicit when-to-use guidance, no statement of prerequisites (e.g., contact must exist), and no mention of the alternative virtuous_list_tags for enumerating all tags.

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 a safe read, so the bar is lower. The description usefully adds which fields come back, but says nothing about pagination behavior, result limits, or the fact that defaults return only 10 records 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 the resource and returned fields front-loaded; the trailing API reference is the only filler and it is brief.

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, single-endpoint list tool with full schema coverage and safety annotations, the definition is largely complete, and with no output schema the field enumeration is genuinely valuable. The only gap is the absence of any pagination or result-count guidance.

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 ranges and defaults are already fully documented in the schema. The description adds no format or usage detail for these parameters, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (the organization's events) and even enumerates the returned fields (name, type, location, start/end, counts, giving). No sibling lists events, so it is unambiguously distinguishable from the contact/gift/query tools.

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

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

The action is self-evidently a list-all operation, but the description gives no explicit when-to-use guidance, no note on pagination or filtering, and no mention of alternatives. Usage is implied rather than stated.

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

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 modest context beyond that by naming the backing endpoint (GET /api/Tag) and the shape of returned records, but says nothing about pagination behavior or result limits despite the presence of 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, zero filler, with the core purpose front-loaded and the usage hint and endpoint following logically. Every sentence carries information.

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

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

For a simple read-only list tool with annotations covering safety, fully documented parameters, and returned fields named inline (compensating for the absent output schema), the description is nearly sufficient. A note on pagination or the distinction from contact-tag listing would close 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 100%, so skip and take are already fully documented with defaults and bounds. The description adds no further parameter meaning, which lands it at the baseline for schema-covered parameters.

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 organization's tags') and even enumerates the returned fields (id, name, tag group), which is stronger than a bare restatement. It stops short of distinguishing itself from the similarly named sibling virtuous_list_contact_tags, so an agent could still confuse organization-level tags with contact-level 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?

Gives a concrete when-to-use rationale: 'Use this to find a tagId before virtuous_add_contact_tag,' explicitly naming the downstream tool that consumes the result. It offers no exclusion guidance against the other tag-listing sibling, but the intended workflow 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 only declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the return shape '{ list, total }' (no output schema exists) and the Contact/Gift-only behavior of full_details. However, it says nothing about pagination interplay, rate limits, or auth scope, so it is solid but not rich.

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

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

Three front-loaded sentences with no filler; the core action and its scoping lead, and secondary detail (return shape, full_details, endpoint) follows. The trailing 'Virtuous: POST /api/<Resource>/Query' is low-value for an agent but harmless and compact.

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 read tool with no output schema, the description covers the return envelope, the distinguished full_details path, and the pointer to QueryOptions for condition vocabulary. Remaining gaps (pagination semantics, archived defaults) are minor and largely handled 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 per the rubric the baseline is 3 even though the schema documents skip/take/sort_by/descending/full_details/include_archived fully. The description adds one genuinely useful cross-reference (parameter/operator values come from virtuous_get_query_options) but otherwise restates what the schema already conveys.

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?

'Run a Virtuous query-builder query against one record type' gives a specific verb plus resource and enumerates the record types it operates on. It distinguishes itself from the simpler locate-style siblings (virtuous_search, virtuous_find_contact) by tying conditions to the query-builder model. An agent can identify this as the flexible/ad-hoc filter tool 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?

It routes the agent to virtuous_get_query_options for valid parameter/operator names and notes that omitting groups returns all records, which is clear contextual guidance. It stops short of explicit when-not-to-use or a named competing sibling (e.g. 'for a single known contact use virtuous_get_contact'), so it is strong but not a full routing rule set.

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 read-only safety profile is covered. The description adds genuinely useful behavioral context beyond that: results come back as hits with highlights grouped by kind, and it names the underlying endpoint (POST /api/Search). It stops short of mentioning pagination defaults or a max result size, which live only 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?

Two compact sentences with the scope front-loaded and return shape second. The endpoint reference is arguably redundant with the title, but the description is well within budget and wastes little space.

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 sketches the return shape (hits, highlights, grouped by kind), which is the main thing an agent cannot learn elsewhere. Combined with 100% schema coverage on params and a readOnly annotation, only minor gaps remain (result limits, pagination defaults).

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/query/filter_types are all documented in the schema. The description adds only the notion of 'grouped by kind' and highlighted hits, which touches filter_types semantics but does not elaborate on query syntax or filter interaction. 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 (full-text search) and enumerates the resources searched (contacts, individuals, campaigns, projects, segments, tags). The 'same search as the Virtuous search bar' framing makes the global scope clear. It does not explicitly contrast itself with siblings like virtuous_search_contacts or virtuous_search_projects, but the enumerated kinds imply the difference.

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 'global search bar' framing and the fact that filter_types lets you narrow kinds, but there is no explicit when-to-use guidance or named alternative for scoped searches (e.g. search_contacts). An agent must infer that this is the broad option and the siblings are the narrow ones.

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 usefully adds that matching is full-or-partial across name/email/phone/address and enumerates the returned fields (id, name, contact type, email, phone, address). It omits any note on rate limits or result caps beyond what the schema states, 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?

Two sentences, front-loaded with the operation and match semantics, followed by return fields. No filler and nothing buried.

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, listing the returned fields is essential and it is done; pagination is adequately covered by the schema's skip/take descriptions. The only real gap is routing guidance against sibling search tools, which the description never addresses.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what the required 'search' string is matched against (name, email, phone, address, fully or partially) – meaning the schema's bare 'Text to match' does not convey. That is genuine added value.

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 (Find) and resource (contacts) plus the fields searched, so the operation is unambiguous. It does not, however, distinguish itself from the closely related siblings virtuous_find_contact or virtuous_search, leaving the agent to guess which entry point applies.

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 despite three plausible siblings (find_contact, search, query). The agent gets a capability statement but no selection criteria.

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

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

readOnlyHint=true already establishes it as a safe read. Beyond that, the description discloses the return payload (balances, financial need, life-to-date giving), which matters because there is no output schema, and it names the backing endpoint. It stops short of noting pagination defaults or result 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 sentences: purpose and returned data first, technical endpoint last. No filler, nothing repeated from the schema.

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

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

For a read-only 3-param search with no output schema, the description covers what is searched and roughly what comes back, and pagination is handled in the schema. A note on result counts or ordering would close 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 coverage is 100%, so skip/take/search are fully documented in the schema and baseline is 3. The description's 'by name or code' merely restates the search parameter's documented behavior, adding no new syntax or matching rules.

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 ('Find projects') with an inline domain gloss ('funds / designations gifts are given to') and the matching key ('by name or code'). This clearly separates it from the sibling get_project (single fetch by ID) and the contact-oriented search 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?

Usage is implied by 'Find ... by name or code', but the description never states when to prefer this over get_project (known ID) or how it relates to virtuous_search / virtuous_query. No exclusions or alternative routing are given.

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