CiviCRM MCP by usefulapi

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

Beyond annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description adds two meaningful facts: the note author is the contact the API key belongs to, and 'Sends nothing' (no notification/email is triggered). This is real behavioral value. It stops short of describing failure modes or what happens if contact_id is invalid.

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 compact fragments with the operation type ('WRITE') front-loaded and no padding. The phrase 'Sends nothing' is slightly ambiguous (no email? no response body?) and would be clearer as 'sends no notification'.

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

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

For a simple three-parameter create tool with annotations and full schema coverage, the description covers author provenance, cardinality, and side-effect absence. The only gap is return behavior (e.g., whether a note id comes back) and error handling, which is minor 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 description coverage is 100%, so all three parameters are documented in the schema itself, giving a baseline of 3. The description only adds that the note attaches to 'a contact's record' and is authored by the API-key contact, which does not meaningfully extend the schema's per-field documentation.

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 ('adds ONE note to a contact's record') and scopes cardinality explicitly with 'ONE', which distinguishes it from a bulk or list operation like civicrm_list_contact_notes. It also names the underlying API (APIv4 Note.create), so the agent knows exactly what entity is created.

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 WRITE prefix and the contrast with the list_contact_notes sibling, but there is no explicit when-to-use/when-not guidance, no prerequisite about the contact existing, and no mention of permission or auth requirements. The 'APIv4 Note.create' hint gives implementation context but not selection guidance.

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

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

Goes well past the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): it discloses the mailing-list consequence, that no email is sent, that duplicate adds are no-ops, and that removed/pending contacts are reset to 'Added'. It even names the underlying APIv4 GroupContact.save upsert semantics.

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

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

Three tight sentences, front-loaded with the WRITE marker and cardinality, then consequences, then edge-case semantics. Every sentence carries decision-relevant information with no filler.

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

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

For a 2-parameter write tool with annotations and no output schema, the description covers effects, side effects, and idempotency thoroughly. The one gap is what the response contains and whether permissions beyond API credentials are required, which the agent must discover at call time.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: the group must be a static group (a constraint not implied by 'integer' in the schema) and the operation is one contact/one group at a time rather than a bulk list.

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?

Opens with 'WRITE: adds ONE contact to ONE static group' — a specific verb, resource, and cardinality/group-type constraint. This clearly separates it from read siblings like civicrm_list_group_contacts and from creating a contact or membership.

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 explicit consent criteria ('only add people who agreed') and rules out the misconception that mail is sent. It does not name an alternative tool (e.g., check membership with civicrm_list_group_contacts first), so it is strong context but not full when/when-not 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?

Annotations already flag openWorldHint=true and idempotentHint=false; the description adds the non-obvious behavioral facts an operator cares about — no deduplication is performed and no notifications/e-mails are triggered ('Sends nothing'). It stops short of saying what a successful call returns (no output schema exists), so the agent cannot anticipate the created contact's identifier.

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

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

Four short sentences, front-loaded with the WRITE/count scope, then the duplicate caveat, then the notification caveat, then the underlying API. 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?

For a 9-parameter create with rich schema descriptions and no output schema, the description covers the two things the schema cannot: no duplicate check and no side-effect messaging. The remaining gap is type-dependent field requirements and the shape of the returned contact, neither of which is stated anywhere.

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 89%, so nearly every parameter is already documented in the schema, including the note that email/phone become the primary values. The description only restates that email and phone are optional, adding no format, conditional-requirement, or type-specific guidance (e.g. that Individual contacts generally need a last name).

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 ('WRITE: creates ONE new contact') and lists the covered entity types (individual, organization, household) plus side-record creation. Naming the underlying APIv4 entities (Contact.create, Email.create, Phone.create) further pins down the exact operation and distinguishes it from civicrm_update_contact or civicrm_add_contact_to_group.

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 gives the when-not and the alternative: 'Does not check for duplicates: search first with civicrm_search_contacts.' An agent knows to call the search sibling before creating when duplicates are plausible, which is the main misuse risk for a create tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description goes beyond them by disclosing two non-obvious side effects: dates/status are derived from the membership type unless supplied, and neither a payment nor any message is produced. It does not address permissions or what happens on duplicate memberships, 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?

Three short sentences, front-loaded with the 'WRITE:' marker so the mutation class is visible immediately. Every clause carries distinct information: scope, derivation behavior, excluded side effects, and backend 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 6-parameter mutation with full schema coverage and no output schema, the definition covers the important gaps. The only omission is what is returned (e.g. the new membership id), which matters slightly since there is no output schema to fall back on.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: start/end dates are optional because the membership type calculates them. That is the key semantic decision an agent must make, and it is stated directly.

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 ('gives ONE contact a membership of a type') plus the underlying API call (Membership.create). The 'ONE contact' qualifier distinguishes it from any bulk/multi-contact path, and the explicit mention of civicrm_record_contribution separates it from the contribution 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?

Names a concrete alternative and the condition that selects it: no payment is recorded, so use civicrm_record_contribution for that. It also sets expectations about notifications ('sends nothing'). The when-not guidance is explicit rather than inferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the description doesn't need to repeat it. It adds real value beyond that by disclosing the fan-out scope of the read: base contact fields plus all Email, Phone and Address records, which tells the agent to expect a wide payload. It omits what happens for a missing/invalid id, but the core behavioral shape is clear.

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 payload is front-loaded, the related-record list follows, and the trailing APIv4 entity list concisely signals implementation scope. No filler.

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

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

For a one-param read tool with no output schema, enumerating the returned fields is exactly the right compensation and it is present here. Minor gaps remain around not-found behavior and whether permissions/site scoping limit results, but nothing essential for invoking 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 coverage is 100% and the schema description already explains contact_id as the cid in the contact's URL. The description only restates 'by id' and adds no format, range, or scoping detail beyond the schema. Baseline 3 is appropriate since the schema carries the 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?

Specific verb+resource ('One contact by id') followed by an enumeration of the fields and related records returned, which makes it clearly distinct from list/search siblings. It never names civicrm_search_contacts or civicrm_list_* explicitly, so the differentiation is inferential 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?

'One contact by id' implies the usage condition (you must already have a contact id) and implicitly contrasts with search tools, but there is no explicit when-to-use/when-not or named alternative. Adequate but leaves the agent to infer the 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value by disclosing the shape of the response (custom fields included, pick-list options exposed), which matters because there is no output schema. It does not mention that the 'action' parameter changes which fields are relevant, a minor gap.

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

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

Three tight clauses: what is returned, when to use it, and the underlying APIv4 call. Front-loaded and waste-free, though the final 'APIv4 <Entity>.getFields' fragment is more implementation trivia than agent-relevant guidance.

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 explaining return content and does so adequately, including the custom-field caveat. It falls slightly short on how the action parameter changes the field set, but for a read-only introspection helper it is otherwise 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 coverage is 100%, so both 'field' and 'action' are already documented in structured form, establishing a baseline of 3. The description only implies the 'entity' parameter through its prose and adds nothing about restricting to a single field or how 'action' affects results.

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 — describing the fields of one CiviCRM entity — and enumerates exactly what metadata is returned (name, label, data type, required, pick-list options). No sibling tool does metadata introspection, and the description makes that role unmistakable.

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 tells the agent when to call it: to find the right field names for civicrm_query and the correct option names for filters and write tools. That routes the agent to the correct sibling dependency rather than guessing field names.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds useful behavior beyond that — result ordering ('newest first'), the enrichment of contact-scoped results with role (source, target, assignee), and the underlying API surface (ActivityContact.get / Activity.get). It does not discuss pagination semantics, but the schema's offset description already points at next_offset.

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

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

Three tight sentences with zero filler: result shape first, the contact_id branch second, the default branch and its filters last, with the API reference as a trailing footnote. Front-loaded and appropriately sized.

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 returns and does so (field list, ordering, role). For a 7-parameter read-only list tool this is close to complete; only pagination/result-size expectations are 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 coverage is 100%, so baseline would be 3; the description goes beyond it by explaining that contact_id switches the query to a contact-participation view and adds a returned role field, and that activity_type/status act as optional narrowing filters only in the non-contact case. That is genuine semantic value the schema's per-field descriptions do not convey.

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

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

States the specific resource (activities: meetings, phone calls, e-mails, follow-ups) and what each record carries (type, subject, status, date, details), plus the ordering ('newest first'). The two-branch structure (with contact_id vs. without) makes it distinguishable from sibling list tools like civicrm_list_events or civicrm_list_cases.

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 describes the two usage modes: 'With contact_id: the activities that contact took part in, with their role ... Otherwise all activities, optionally of one type or status.' That is clear conditional guidance for choosing parameter combinations, but it names no alternative sibling tool (e.g., civicrm_query for arbitrary filters) and gives no exclusions.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds a genuinely useful prerequisite (CiviCase component must be enabled) and notes the underlying APIv4 entities, but says nothing about pagination behavior or result volume.

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 sentences, resource first, then scoping, then prerequisite. The trailing 'APIv4 CaseContact.get / Case.get.' is terse but adds implementation context rather than noise.

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 does name the returned fields, and it covers the key precondition and the contact scoping. For a simple read-only list tool with fully documented parameters, only pagination/ordering details 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%, so limit/offset/status/contact_id are already documented in detail, including the status-applies-only-without-contact_id rule. The description adds only the 'client of' framing for contact_id, which is marginal 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+resource (list CiviCase cases) and names the fields returned (subject, case type, status, dates), plus the contact_id scoping behavior. It is distinguishable from generic siblings like civicrm_query, though it does not explicitly contrast with them.

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

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

Usage is implied: list cases, optionally scoped to a contact's client cases. It never states when to prefer this over civicrm_query or civicrm_list_entities, nor any exclusion, so routing between siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds two facts not in structured data: results are sorted newest first, and each note carries subject, text, author and timestamp — both directly useful for consuming the response.

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, and the resource scope plus sort order arrive before the APIv4 implementation note.

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

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

With no output schema, the description compensates by naming the returned fields and ordering, and pagination is covered in the schema. Minor gap: no mention of an empty result or what happens for an unknown contact_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 pagination semantics (limit, offset, next_offset) are fully documented there. The description only reinforces the single-contact scoping; a 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+resource ('notes recorded on one contact') with the scope narrowed to a single contact, which cleanly separates it from civicrm_add_contact_note and the broader query tools. It doesn't explicitly name a sibling, 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 tool's use case (read the notes on a known contact) is implied but there is no explicit when-to-use/when-not, and no pointer to alternatives such as civicrm_query or civicrm_get_contact if the agent lacks 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds genuinely new behavior: results come back 'newest first' and 'Test contributions are left out'. It stops short of describing pagination or volume expectations, but adds real value beyond the structured metadata.

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 clauses: what it returns, how to filter, then the exclusion rule and APIv4 source. Front-loaded with the payload fields and zero 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 8 all-optional params, no output schema and annotations covering safety, the description supplies the missing pieces an agent needs: the shape of returned records, ordering, and the test-record exclusion. Only a hint about pagination/expected result volume is absent, and the schema's offset parameter largely covers that.

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 every parameter (limit, offset, status, date_from/date_to, contact_id, min_amount, financial_type) is already documented with formats and examples. The description only restates the filter set, adding no syntax or semantics 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?

Specific verb+resource: 'Contributions (donations, membership dues, event fees)' with the returned fields enumerated and sort order stated. It is clearly distinguishable from siblings like civicrm_list_memberships, civicrm_list_participants and civicrm_record_contribution.

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

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

The filter list ('Filter by contact, status, financial type, date range and minimum amount') implies when the tool applies, but there is no explicit when-not guidance or pointer to alternatives such as civicrm_query for compound/custom filtering. Usage must be inferred from the filters 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 annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful domain context — that results include entities from installed extensions and carry a short description, and that it maps to APIv4 Entity.get — but says nothing about result shape, ordering, or size.

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 what is returned, followed by how to use the output and the underlying API call. No filler and no redundancy with 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 simple, no-required-param discovery tool with annotations and no output schema, the description covers discovery, scope (core + extensions), and downstream usage. Only minor gaps remain, such as whether results are paginated or sorted.

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 a single optional parameter with 100% schema description coverage ("Only entities whose name or title contains this text"), so the schema already carries the semantics. The description never mentions filtering, which is acceptable at this coverage level but adds no 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?

States a specific verb+resource: lists the APIv4 entities available on this site, with concrete examples (Contact, Contribution, Event) and the extension caveat. It also scopes itself relative to siblings by naming civicrm_get_fields and civicrm_query as the consumers of its output.

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?

"Use the names with civicrm_get_fields and civicrm_query" positions this clearly as the discovery step before those tools, which is real routing guidance. It stops short of explicit exclusions (e.g., skip this if you already know the entity name), so it is not a 5.

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

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

Annotations already establish read-only, non-destructive, open-world behavior, so the description adds real value beyond them: template events are filtered out, results are ordered (upcoming first) when the flag is set, and the return envelope is described field-by-field. It stops short of noting pagination semantics beyond what the schema says.

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

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

Four short, dense sentences with the returned-field summary front-loaded and behavioral notes trailing. No filler, though the field enumeration is arguably redundant with the response and could be tighter.

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 five-optional-parameter read tool with full schema coverage and read-only annotations, the description covers return contents, default filtering (templates out), and ordering. Missing only an explicit note that results can be paged via next_offset and what an empty result means.

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

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

Schema coverage is 100%, so all five parameters are self-documenting; the description only touches `upcoming_only`, and its wording ('Upcoming events first when upcoming_only is set') blends ordering with filtering, which is slightly less precise than the schema's 'have not ended yet'. Baseline 3 applies since 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?

Implies a list operation over events and enumerates the fields returned (title, type, dates, active/public, max participants, summary), plus third-person specifics like template exclusion and 'APIv4 Event.get'. The verb is only implicit ('Events with ...') and relies on the tool name, but the resource and scope are unambiguous and no sibling tool targets events.

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 conditional context for `upcoming_only` and states that template events are excluded, which is implied usage guidance. However, it never says when to pick this tool over e.g. civicrm_query or civicrm_list_entities for event data, nor any prerequisites (permissions, campaign/date scoping).

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuine context the annotations don't: smart groups are excluded, and the returned fields include membership status (Added/Removed/Pending). It stops short of disclosing default behavior when neither identifier is supplied or what pagination looks like.

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

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

Two tight sentences front-load the core behavior and the smart-group exclusion, followed by the APIv4 entity reference for traceability. Nothing is redundant, though the parenthetical could be split to make the two modes easier to parse.

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 zero required parameters and no output schema, the definition should state what happens when neither group_id nor contact_id is provided (list everything? error?). It covers return fields informally but leaves this default-behavior gap for a tool an agent can call with no arguments.

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

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

Schema coverage is 100% and every parameter carries a description including defaults and the next_offset pattern, so the schema does the heavy lifting and a baseline 3 applies. The description adds only the conceptual framing of group_id vs contact_id as opposite directions, which the schema descriptions already convey.

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

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

The description names the two access modes precisely: members of one static group, or groups of one contact, plus what fields come back (contact, group, membership status). It differentiates itself from civicrm_list_groups by pointing at the underlying GroupContact.get entity, though it never names sibling tools as 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?

Usage is implied by the dual-mode phrasing and there is a partial exclusion ('Smart groups are computed by CiviCRM and not listed here'), which is a real when-not. But it gives no explicit guidance on when to prefer this over civicrm_list_groups or civicrm_list_memberships, and the schema fields are what actually route the caller (group_id 'from civicrm_list_groups').

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds useful domain context by explaining that groups come in static, smart, and mailing-list flavors, but says nothing about result-set shape, ordering, or the default exclusion of inactive groups beyond what the schema states.

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

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

Two compact fragments with the entity definition front-loaded and no filler. The trailing 'APIv4 Group.get' is terse and marginally useful for technical callers, though it slightly crowds out the usage guidance that is missing.

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

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

For a low-complexity, read-only list tool with full schema coverage and safety annotations, the description is largely sufficient: it defines the entity, enumerates representative returned fields in the absence of an output schema, and points at the underlying API. The remaining gap is that it doesn't clarify group-vs-group-membership selection against civicrm_list_group_contacts.

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

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

Schema description coverage is 100%, and the schema fully documents limit, offset (including the next_offset handoff), title filter, and the active_only default. The description's mention of title/description/visibility/type refers to returned fields, not parameters, so it adds no semantic depth to the four inputs. Baseline 3 applies.

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

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

The description names the resource (contact groups) and disambiguates the entity with concrete domain vocabulary — mailing lists, static groups, smart groups — plus the fields surfaced. It never names the closest sibling (civicrm_list_group_contacts), so the agent must infer the groups-vs-group-members distinction on its own.

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 statement of when to reach for this tool, no prerequisites, and no alternatives offered — neither civicrm_list_group_contacts nor civicrm_query is mentioned as an option. The 'APIv4 Group.get' suffix is an implementation reference, not usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description still adds real behavioral facts: test memberships are silently excluded and the underlying APIv4 Membership.get semantics apply. It omits pagination defaults and result shape, but the schema covers limit/offset.

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 returned fields first and filters second; no filler. The opening is a noun phrase rather than a sentence, which costs a little immediate clarity.

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

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

With no output schema, the description compensates by enumerating returned fields, and it flags the hidden test-membership exclusion. Pagination and limits are left entirely to the schema, which is acceptable given 100% schema coverage.

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 each of the seven parameters is already documented with examples and formats. The description restates the filter set (contact, status, type, end-date) but adds no syntax or edge-case meaning, and notably omits ends_after while mentioning only 'ending before a date'.

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

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

States the resource (memberships) and enumerates what each record carries (contact, type, status, join/start/end dates), plus the backing API call (APIv4 Membership.get). It is clearly a read/list tool and distinguishable from civicrm_create_membership, though it never explicitly names a 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?

Gives one concrete use case ('those ending before a date (renewal follow-up)') and a default-scope rule ('Test memberships are left out'), which is genuinely helpful. It does not say when to prefer civicrm_query or other list tools, nor any exclusion conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new behavioral facts: test registrations are excluded from results and the underlying API is Participant.get. It does not discuss result volume or pagination behavior beyond what the schema states.

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

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

Three dense sentences, front-loaded with the resource and returned fields, followed by filtering and exclusion rules. No filler or repetition of the title.

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

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

With no output schema, the description correctly compensates by listing the fields returned, and it flags the test-registration exclusion. Minor gaps: no mention of ordering or total count, though pagination is handled in the schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by naming the exact filter parameters and giving concrete status values (Registered, Attended, Cancelled) that map to the loosely-typed status string. Limit/offset semantics are left entirely to the schema.

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

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

Opens with a specific resource ('Event registrations') and enumerates the fields returned, which distinguishes it from civicrm_list_events and civicrm_list_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?

'Filter by event, contact or status' gives clear usage context and tells the agent the three supported selection axes. There is no when-not-to-use guidance or pointer to civicrm_register_participant for writes, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful return-content context (relationship type, start/end date, active status), but does not disclose pagination behavior or any auth/scope constraints beyond 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?

A single tight sentence front-loads the resource and scope, then lists key returned attributes and the underlying API method. No wasted language.

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 is nearly complete: it identifies the resource, scope, and key return fields. It could add pagination/return-shape guidance, but the 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 100%, so all four parameters are already explained. The description reinforces that only one contact's relationships are returned, but does not add syntax or behavior beyond the schema for limit, offset, contact_id, or active_only.

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: relationships of one contact, with examples of relationship types and returned fields. It clearly separates this from contact search or group listing, though it doesn't explicitly name a sibling alternative.

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 "relationships of one contact," but there is no explicit guidance on when to choose this vs. civcrm_search_contacts, civcrm_list_group_contacts, or civcrm_query, and no exclusions or prerequisites.

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

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

Annotations only declare write/non-destructive/non-idempotent; the description goes further by disclosing the no-side-effect storage semantics and the attribution default (added by the API key's contact unless source_contact_id is given). These are exactly the behaviors an agent cannot infer from the structured fields.

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

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

Three tight sentences, front-loaded with 'WRITE:' so the mutation nature registers immediately, and every clause carries payload (scope, no-send caveat, attribution default). No filler.

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

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

For an 8-parameter mutation with annotations but no output schema, the description covers the important unknowns: side effects and record ownership. It does not say what comes back (e.g. the new activity id) or that each call creates a distinct record given idempotentHint=false, which leaves a small 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% and every parameter already carries a description, including the source_contact_id default and the with_contact_ids meaning, so the description's restatement adds little. The mention of with_contact_ids and source_contact_id is consistent but not additive enough to exceed the baseline.

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

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

States a specific verb and capped scope ('WRITE: records ONE activity') plus the resource kind (meeting, phone call, e-mail), which separates it cleanly from civicrm_list_activities and civicrm_add_contact_note. The 'with one or more contacts' clause pins down the relationship the record establishes.

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?

Makes the key when-not explicit: an Email-type activity only stores the record and does not send mail, so an agent won't call this expecting delivery. It gives clear creation context but never names a sibling to use instead (e.g. civicrm_list_activities for reading, civicrm_get_fields for valid type names is only referenced from the schema).

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

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

Beyond the readOnlyHint/destructiveHint annotations, it discloses a real behavioral constraint: credential fields and system entities (settings, payment processors, mailings, users) are refused. That prevents wasted calls and is not derivable from the annotations. It does not describe the response shape (no output schema) or pagination continuation beyond the word 'page'.

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

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

The purpose and key constraint are front-loaded in the first sentence, and the refusal policy closes the paragraph. The three examples are dense but the second and third both demonstrate where-clause syntax, so there is slight redundancy that could be trimmed.

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 generic 6-parameter query tool with no output schema, the description covers entity/field discovery, filter syntax, joins, pagination, and refusal rules. The only meaningful gap is that the shape of the returned payload and the next_offset continuation are not explained in prose.

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 100% schema coverage the baseline is 3, and the description genuinely adds meaning the regex patterns cannot: field names may be joined (`contact_id.display_name`) or request option text (`status_id:label`), plus a concrete where/select example. limit/offset/order_by semantics are left entirely to the schema.

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

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

States a specific verb+resource+mechanism: 'Read records of ANY CiviCRM entity with APIv4 Entity.get.' The 'ANY entity' framing distinguishes it from the specialized list_* siblings, which are scoped to one entity type, so an agent can immediately tell this is the generic escape hatch.

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 concrete usage context via three worked examples (Tag, Campaign with where, Contribution with select+where) and routes the agent to civicrm_list_entities and civicrm_get_fields to resolve entity/field names. It never explicitly says when to prefer a sibling like civicrm_list_contributions over this generic query, so alternatives remain implicit.

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 a non-read-only, non-idempotent, open-world write; the description adds genuinely new context: it only stores the financial record, charges nothing, sends nothing, and the amount surfaces in reports and giving history. That is real side-effect disclosure beyond the hints, though it does not mention permissions or what the call returns.

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 sentences, front-loaded with the 'WRITE:' marker, then scope, then the duplicate-check. Every sentence contributes and nothing is restated.

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 9-parameter mutation with no output schema and full schema coverage, the description covers scope, side effects, and the duplicate-avoidance step. Minor gaps remain around permission requirements and what identifier is returned, but nothing needed 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 9 well-documented parameters, so the schema carries parameter meaning. The description adds no format, default, or constraint detail beyond it, 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 ('records ONE contribution') plus a parenthetical defining what counts as a contribution, and names the sibling (civicrm_list_contributions) it is not. An agent can separate it from the list 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?

Gives a concrete pre-call check ('Check civicrm_list_contributions first to avoid a duplicate') and clarifies what the tool does not do (no card charge, no receipt), which frames when it applies. It stops short of explicit when-not-to-use conditions or other alternatives, so it is clear context rather than 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?

Goes well beyond the annotations: it discloses that capacity and fee limits are not enforced, that no payment is processed, and that no confirmation e-mail is sent — exactly the side-effect boundaries an agent needs before firing a write. It also names the backing API (APIv4 Participant.create), confirming the mutation is a single-record create.

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 the write nature front-loaded, then the exclusion list, then the API reference. 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?

For a mutation tool with no output schema, it covers scope, non-enforced checks and side effects thoroughly. The only omission is what comes back (e.g. the new participant id), which would help an agent chain a follow-up call.

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

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

Schema coverage is 100%, so event_id, contact_id, role, status and source are already documented in the schema. The description only implies the two required ids via 'ONE contact for ONE event' and adds no extra meaning for role/status/source, so the baseline 3 applies.

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

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

States a specific verb and resource ('registers ONE contact for ONE event') and pins down cardinality and the underlying object (a participant record). This clearly separates it from civicrm_list_participants and the contact-creation 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?

The negative scoping ('does not take payment', 'sends no confirmation e-mail') tells the agent when this tool alone is insufficient, implying record_contribution is needed for fees. It stops short of naming the alternative tool or stating prerequisites (e.g. event/contact must exist first), so it falls just below a 5.

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

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

Annotations already declare readOnlyHint and non-destructive, so safety is covered; the description adds real value with the soft-delete exclusion ("Trashed contacts are left out") and the exact projected return fields. It stops short of stating result cap behavior or whether matches are ranked, which an agent planning pagination would want.

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: purpose and searchable fields first, then the trashed exclusion, then the return shape and APIv4 provenance. Nothing is redundant.

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

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

For a read-only search with 4 well-documented parameters and no output schema, the description supplies the entity subtypes, the exclusion rule, and the returned fields, which is essentially everything needed to call it correctly. Only routing versus civicrm_get_contact and pagination hints are absent.

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 limit, offset, query and contact_type are already fully documented, including offset chaining via next_offset. The description only restates query semantics and the optionality of contact_type, adding little 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 and resource ("Find contacts") plus the searchable fields (name, e-mail, phone) and the entity subtypes (people, organizations, households). It does not explicitly distinguish itself from the sibling civicrm_get_contact (ID lookup) or civicrm_query, so an agent still has to infer which to pick.

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

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

Usage is implied by "by a word in their name, e-mail address or phone number" and by noting that an empty query lists contacts, but there is no explicit when-to-use/when-not or routing to civicrm_get_contact for known IDs. The trashed exclusion is a scope note rather than 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 destructiveHint=true and idempotentHint=true, yet the description adds non-obvious behavior: only supplied fields are mutated (so unspecified data is untouched), and flipping a do-not flag to false re-enables a contact the person may have declined. That last warning is a consent-safety nuance no structured field conveys.

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

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

Three tight sentences with the write nature front-loaded, the field inventory second, and the safety caveat last. No filler, and the highest-risk instruction is placed where it will be read.

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 13-parameter mutation tool with no output schema, it covers scope, partial-update behavior, and the consent hazard, which is most of what an agent needs. It leaves household_name/organization_name unexplained and says nothing about the return payload or validation failures (e.g., contact_id not found).

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 15% schema coverage across 13 parameters, the description must compensate, and it does: it names first/last name, job title, source, preferred language, and all four do-not flags plus bulk-mail opt-out, explaining what the opt-out means. It omits household_name and organization_name, which are in the schema but unmentioned, leaving a real gap given the low 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?

Opens with an explicit 'WRITE:' marker, states the verb (changes), resource (ONE existing contact), and enumerates the affected field groups, plus names the underlying APIv4 method. An agent can distinguish this at a glance from civicrm_create_contact, civicrm_get_contact, and the list_* 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?

The 'ONE existing contact' scope plus partial-update semantics make clear this is for modifying rather than creating, and the do-not-flag caution gives an explicit when-you-should-not rule. It stops short of naming civicrm_create_contact as the alternative for new records or stating prerequisites like contact existence.

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 establish readOnlyHint=true and destructiveHint=false, so safety need not be restated. The description adds real value beyond them: it discloses the permission-scoping behavior of the entire API surface and the underlying implementation path (GET /civicrm/authx/id, then APIv4 Contact.get), which explains latency and the openWorldHint. It could say more about failure modes when the key is unauthenticated or expired.

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

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

The identifying information is front-loaded in the first clause, and the permission-scoping note is a genuinely useful second sentence. The trailing implementation path is slightly technical, but it is short enough not to bury the payload.

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 has to carry the return values itself, and it does so by naming the returned fields. It gives a complete picture for a zero-parameter read tool, though it does not specify the shape or type of the 'how it authenticated' value, leaving a small 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter surface the description could explain. Nothing in the description contradicts the empty input schema.

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

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

The description states a concrete resource — the CiviCRM contact the API key belongs to — and enumerates the identifying fields returned (contact id, display name, contact type), which sets it apart from civicrm_get_contact, which needs an id supplied by the caller. What is missing is an explicit statement that this is the zero-argument identity lookup versus that sibling, so differentiation is implied rather than stated.

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

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

The description points toward the use case by saying everything else is limited to that contact's permissions, which implies calling this first to establish scope. However, it never explicitly says when to use this instead of civicrm_get_contact or how to handle the case where the agent already knows the contact id, so 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.