civicrm-mcp

by YogiAdhik

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.2.0
Disambiguation5/5
Every tool has a clear, distinct purpose. There is no overlap between tools like find_contacts vs get_contact or list_entities vs describe_entity. The descriptions further clarify each tool's role.
Naming Consistency5/5
All tools follow a consistent 'civicrm_verb_noun' pattern (e.g., list_events, create_contact, tag_contacts). The few exceptions like whoami and system_info are standard and do not break the overall pattern.
Tool Count4/5
25 tools is on the higher side but appropriate for a comprehensive CRM server covering many entities (contacts, events, contributions, groups, memberships, tags, etc.). Each tool serves a specific need and the count feels justified.
Completeness4/5
The tool set covers most common CRM operations for reading and writing major entities. Some operations are missing (e.g., listing groups, updating contributions), but the generic civicrm_api4 tool can fill gaps if enabled. Overall, the surface is solid.
Average 3.9/5 across 25 of 25 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions an environment variable requirement, but omits key traits such as whether the tool is idempotent, what the response format is, or any side effects (e.g., receipts, membership updates). This is minimal for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, followed by a critical prerequisite. No wasted words; every sentence adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters (including a nested 'extra' object), no output schema, and no annotations, the description is too brief. It fails to explain return values, error handling, or the purpose of the 'extra' object, leaving significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 73%, so the schema already documents most parameters. The description adds no additional parameter-specific clarification. Per guidelines, baseline is 3 when coverage is high, and the description does not elevate this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Record a donation / contribution for a contact', which is a specific verb and resource. The name 'civicrm_record_contribution' aligns with this, and among sibling tools like civicrm_get_contributions (read) and civicrm_api4 (generic query), this tool is clearly the dedicated write operation for contributions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., when to use civicrm_api4 for custom contribution creation, or when to use civicrm_update_contact for contacts). Only a prerequisite 'Requires CIVICRM_ALLOW_WRITES=true' is given, which is a system constraint, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry full burden for behavioral traits. It only mentions the write permission prerequisite but fails to disclose success/failure behavior, side effects, or return format. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with one sentence plus a prerequisite. However, it is not under-specified; it efficiently states the purpose and a critical requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite high schema coverage, the description lacks context on return values, error handling, or usage scenarios. Given 8 parameters and no output schema, the description is too brief to fully inform an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 88%, so most parameters have descriptions in the schema. The tool description does not add any parameter-level information beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Record' and the resource 'Activity' against a target contact, which is specific and distinguishes from siblings like add_note or create_contact by referencing the CiviCRM Activity entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes a prerequisite ('Requires CIVICRM_ALLOW_WRITES=true') but provides no guidance on when to use this tool versus other write tools like civicrm_add_note or civicrm_create_contact, nor does it mention scenarios where logging an activity is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the write operation and the chaining behavior, but does not mention side effects, idempotency, return values, or error conditions. The prerequisite is useful but minimal for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, 30 words, front-loaded with action and key behavior. No wasted words. Ideal for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite moderate complexity (9 parameters, no output schema, no annotations), the description is minimal. It omits return value format (e.g., the created contact ID), error scenarios, and defaults. For a creation tool, the agent needs to know what happens on success and failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 44%, meaning only 5 of 9 parameters have descriptions. The description adds context that email and phone are chained, which adds meaning beyond the schema. However, it does not explain 'extra' or provide guidance on required fields. At 44% coverage, the description should compensate more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new CiviCRM contact') and the resource, along with a key feature ('Chains email and phone creation when provided'). This distinguishes it from siblings like civicrm_update_contact or civicrm_find_contacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('Requires CIVICRM_ALLOW_WRITES=true') but does not provide guidance on when to use this tool versus alternatives, such as when to update vs create. Usage is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden for behavioral disclosure. It only states the function and output, but omits any mention of side effects (none expected), ordering, pagination, or that it is a read-only operation. This is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no unnecessary words. The first sentence states the action and criteria, the second lists the return fields. Efficiently communicates essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with two parameters and no output schema, the description is minimally adequate. It lists inputs and outputs but lacks details on limit behavior, result ordering, or potential edge cases like no results. A fuller description would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the query parameter with detail (matches display_name, first_name, last_name, or primary email), covering 50% of parameters. The description echoes 'by name or primary email' but does not add information about the limit parameter. Overall, the description adds marginal value beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool searches CiviCRM contacts by name or primary email and lists the returned fields (id, display name, type, primary email, phone). This distinguishes it from siblings like civicrm_get_contact (single contact by ID) and civicrm_list_entities (generic list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (search by name/email) but does not explicitly contrast with alternatives such as civicrm_get_contact or civicrm_run_saved_search, nor does it mention when not to use this tool. No exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It reveals default filtering and returned fields, but does not explicitly state that the tool is read-only or discuss side effects, rate limits, or prerequisites. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, well-structured sentence. Action first, then defaults, then return fields. No extraneous words; every piece of information earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with three optional parameters and no output schema, the description covers key aspects: default filtering and return fields. Missing a statement about read-only nature and possible pagination (though limit is in schema). Nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (public_only and upcoming_only have descriptions). The tool description adds context about default behavior and return fields, but does not clarify the limit parameter beyond schema constraints. The added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists CiviEvent events, specifies default behavior (upcoming only), and enumerates returned fields (id, title, type, dates, flags). It distinguishes from sibling tools like civicrm_list_entities (generic) and civicrm_register_for_event (write).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For instance, if advanced filtering is needed, civicrm_api4 might be more appropriate, but that is not mentioned. The description only states defaults and return fields without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the operation preserves history and is not a hard-delete, but does not detail potential side effects, error conditions, or permission requirements beyond the environment variable. Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences deliver essential information without redundancy. Every sentence adds value: action, behavioral note, and requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers the main behavior and a requirement, but lacks details on error handling (e.g., what happens if contact is not in group) or return value. It is adequate but could be more thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: only 'group_id' has a description. The description does not add any parameter-level information beyond the schema. 'contact_id' remains undocumented, and no clarification is provided on how to obtain valid IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action: 'Mark a contact as Removed from a group' and distinguishes it from hard-deletion. It clearly identifies the resource and operation, differentiating from sibling tool 'civicrm_add_to_group'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a requirement (CIVICRM_ALLOW_WRITES=true) but does not provide explicit guidance on when to use this tool versus alternatives like 'civicrm_add_to_group' or other contact management tools. Usage is implied by the purpose but not fully articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It claims safety and cheapness but does not elaborate on permissions, error handling, pagination, or return format beyond 'rows via SearchDisplay.run'. Insufficient detail for a mutation-like execution tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, pairing suggestion, and value proposition. No fluff, information is front-loaded, and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite moderate complexity (5 params, nested objects) and no output schema, the description omits return format, pagination behavior, and error scenarios. It does not fully equip an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%, and the description adds no extra meaning to parameters. The schema already describes 'search' as name/id, 'display' as optional, etc. With moderate coverage, a score of 3 is appropriate as the description does not compensate for missing details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Execute a SavedSearch and return its rows via SearchDisplay.run', clearly specifying the verb and resource. It distinguishes from siblings by pairing with civicrm_list_saved_searches, and values it as the safest/cheapest way to run complex queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use: for admin-curated complex queries. It suggests pairing with civicrm_list_saved_searches to discover searches. However, it does not explicitly list exclusions or alternative tools for ad-hoc queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the write permission requirement but omits other behavioral details such as idempotency, error handling, or whether duplicate notes are allowed. For a mutation tool, this is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise, front-loaded sentences. The first sentence states the action and targets, the second adds a usage guideline and requirement. Every sentence is essential, and there is no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should ideally mention the return value (e.g., note ID). It covers the required environment variable and entity types, but omits side effects and what the tool returns. For a simple creation tool, it is adequate but has a clear gap in return value specification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description does not add meaningful information beyond the schema—it reiterates the purpose but does not clarify parameter relationships or constraints. No additional semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the action ('Attach a free-text Note') and explicitly lists the supported entity types (contact, contribution, activity, case, relationship). It clearly distinguishes this tool as the one for adding unstructured notes among sibling tools, none of which serve the same purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use notes ('unstructured context that doesn't belong in a custom field') and mentions the environment variable requirement (CIVICRM_ALLOW_WRITES=true). It provides context but does not explicitly name alternatives or when not to use, though the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states it returns fields and actions but does not disclose that it is a read-only operation, any authentication requirements, or potential response size. The description lacks critical behavioral context beyond the basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary purpose, and contains no fluff or redundant information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain the return structure more thoroughly. It mentions fields and actions but not the format (e.g., array of field definitions). It also omits edge cases or error handling. For an introspection tool, it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters well. The description adds minimal extra value by mentioning 'incl. custom fields' and 'actions', but this aligns with the schema descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it introspects an APIv4 entity, returning fields and actions. It also distinguishes itself from the sibling tool civicrm_api4 by specifying 'Call this before civicrm_api4 when unsure of field names or action support.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to use this tool before civicrm_api4 when uncertain about field names or actions, providing clear context. However, it does not mention alternatives like civicrm_describe_field_options or specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a behavioral requirement (the environment variable for writes), but does not describe side effects, error handling, or response format. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are both concise and front-loaded. The first sentence states the core purpose, the second gives a critical usage condition. No redundant words or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, 2 required, no output schema, and no annotations, the description is too minimal. It does not cover return values, error conditions, or behavior for optional parameters. A write operation requires more context to ensure correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, and the tool description adds no additional meaning to parameters. It does not explain the purpose or constraints of the 6 parameters (e.g., contact_id, event_id) beyond the schema's limited descriptions. The description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a Participant record') and the context ('registering a contact for an event'). It uses a specific verb and resource, distinguishing it from sibling tools like civicrm_create_contact or civicrm_add_to_group. This is a clear, unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear prerequisite ('Requires CIVICRM_ALLOW_WRITES=true'), which guides usage. It does not explicitly state when not to use or compare with alternatives, but the context of registration is distinct enough for an agent to differentiate. Lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses auto-calculation of dates and the required environment variable. However, it does not mention side effects, error scenarios, or whether the operation is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with key information, no wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, 8 parameters including a nested object. Description omits return value, error handling, and details on the 'extra' parameter. For a creation tool, the agent lacks information on what happens after success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 63%. The description adds no new parameter-specific information beyond what the schema already provides (e.g., auto-calculation is a behavior, not parameter semantics). Since coverage is moderate but not low, baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a Membership record for a contact'. It specifies the resource (membership) and action (create), and adds a specific behavioral detail about auto-calculation of dates. This distinguishes it from sibling tools like civicrm_create_contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions a prerequisite (CIVICRM_ALLOW_WRITES=true) but does not explicitly compare to alternatives or provide when-not-to-use guidance. It implies usage for creating memberships, but lacks context on when to prefer this over other tools like civicrm_update_contact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states idempotency and the need for CIVICRM_ALLOW_WRITES=true, which are important traits. It could mention error behavior for non-existent contacts or tags, but overall it covers key behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loading the purpose in the first sentence and adding key behavioral details in the second. Every sentence is essential and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters, no output schema, and no annotations, the description covers the main aspects: action, idempotency, and prerequisite. It could mention that contacts and tag must exist, but it is sufficiently complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 no significant meaning beyond the schema; the idempotency note is behavioral rather than parameter-specific. The schema already describes both parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Add a tag to one or more contacts', specifying the verb and resource. It distinguishes from sibling tools like 'civicrm_untag_contacts' and 'civicrm_add_to_group' by focusing on tagging.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions idempotency and the required environment variable, which are useful usage hints. However, it lacks explicit guidance on when to use this tool versus alternatives like 'civicrm_add_to_group' or 'civicrm_untag_contacts'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It correctly describes a read operation ('list') and adds value by mentioning resolved display names and status labels, but does not explicitly state idempotency or lack of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose and filters, second adds behavioral detail about resolved fields. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and no output schema, the description covers purpose and filters but lacks details on return structure, pagination, sorting, or error behavior. It mentions resolved fields but not the full response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), so baseline is 3. The description lists filter types (contact, date, status, financial type) which map to parameters, but adds little beyond what the schema already provides. No parameter-specific syntax details are added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists contributions (donations, dues, event fees) and specifies optional filters. It distinguishes from sibling tools like civicrm_record_contribution (create) and civicrm_list_entities (generic).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing contributions but does not explicitly state when to use vs alternatives or provide exclusions. The context of siblings helps differentiate, but no explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses return data (core profile plus primary email/phone/address) and the `fields` override option. However, it omits error behavior (e.g., contact not found), permission requirements, or whether the operation is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no superfluous information. The first sentence front-loads the purpose and resource, and the second covers the key parameter behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description states the default return set. For a simple fetch tool with two parameters, it provides sufficient context for an agent to invoke it correctly, though error handling and permission details are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the default return set and how `fields` overrides it, going beyond the schema's basic type and requirement info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'single CiviCRM contact by id'. It distinguishes from sibling tools like civicrm_find_contacts (search) and civicrm_list_entities (list) by specifying it returns a single contact's core profile plus primary contact methods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific contact ID and want the core profile, but does not explicitly state when not to use it or mention alternatives among siblings. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It mentions automatic resolution of display name and direction, which adds useful context. However, it does not explicitly state that the tool is read-only, discuss authentication needs, or note any rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the core purpose, and includes relevant detail about relationship types and automatic resolution. Every sentence adds value with no redundancy or unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary function well for a low-complexity read tool. However, it omits discussion of pagination (limit parameter), ordering, or the structure of the return value, which could be helpful given the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter schema coverage is 67%, with descriptions for contact_id and active_only. The description reinforces contact_id's purpose but adds no new semantics beyond the schema. The limit parameter lacks a schema description and is not mentioned in the tool description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'relationships', and the scope 'for a contact'. It specifies relationship types (family, employer, membership, custom types) and distinguishes from sibling tools like civicrm_get_contact and civicrm_list_entities by focusing exclusively on relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to list relationships for a contact. It implicitly differentiates from alternatives by being relationship-specific, but does not explicitly exclude other cases or mention when-not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It discloses that the tool sends an email (side effect) and requires a write-allowed env variable. However, it does not mention idempotency, error behaviors, or what happens on duplicate sends, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines the action, second adds a key prerequisite. No wasted words or repetition, efficiently conveying essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple action tool without output schema, the description covers purpose and a critical requirement. It could mention success/failure indications, but given the tool's straightforward nature, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a description. The tool description adds overall purpose but no additional parameter-level meaning beyond what's in the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Send (or re-send)' and the resource 'standard receipt email for a contribution'. It distinguishes this tool from siblings like civicrm_get_contributions or civicrm_record_contribution by focusing on the specific action of sending a receipt.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that the tool triggers an outbound email and requires CIVICRM_ALLOW_WRITES=true. While it doesn't explicitly mention when not to use it or alternatives, the sibling list contains no other receipt-sending tool, making usage straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses idempotency ('updates an existing row rather than creating duplicates') and a write permission requirement. Since no annotations are provided, this is good but could mention error handling or additional side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and key behavioral trait (idempotency). No unnecessary words, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with no output schema, the description covers action, idempotency, and a requirement. It could be slightly improved by noting error conditions or expected behavior when contact already in group, but meets minimum completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only group_id has a description). The tool description does not add any parameter meaning beyond what the schema provides, failing to compensate for the missing contact_id description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and resource 'contact to a group', specifying the exact status 'Added' and idempotent behavior, which distinguishes it from siblings like civicrm_remove_from_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a critical prerequisite: 'Requires CIVICRM_ALLOW_WRITES=true', which helps the agent decide readiness. It lacks explicit 'when to use' or 'when not to use' compared to alternatives, but the sibling set includes a removal tool, so purpose differentiation is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It explains the nature of the records listed but lacks details on pagination, ordering, or any side effects. Adequate for a simple listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words. Very efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional params and no output schema, the description explains purpose and relationship to sibling tool. Could mention return structure but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds no parameter details beyond the schema; schema coverage is 50% (only 'query' has a description). The description does not compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists SavedSearch records and specifies they are SearchKit queries built in the UI. Also distinguishes from sibling tool civicrm_run_saved_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to discover what's available to run via civicrm_run_saved_search,' providing clear context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose behavioral traits such as error handling, performance characteristics (beyond 'far cheaper'), auth requirements, or output format. Minimal behavioral context beyond basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states core purpose, second provides context and comparison. No redundant words. Front-loaded with key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 params and no output schema, the description covers purpose, usage context, and example. However, it lacks details on return format and error conditions, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value by explaining the concept of 'option list (pseudoconstant values)' and giving example field values like 'activity_type_id'. This reinforces the schema descriptions but doesn't add substantial new information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns option list for a single field on an entity, using specific verb 'return' and resource 'option list for a single field'. It distinguishes itself from sibling 'civicrm_describe_entity' by noting it's cheaper and focused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'when you only need to know the valid values for one enum-like field'. Provides alternative 'civicrm_describe_entity' and notes it's cheaper. Example given further clarifies usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses that EntityTag rows are hard-deleted, which is critical behavioral info. It also notes the required environment variables. However, it does not cover error behavior or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (two sentences), front-loaded with the primary purpose, and every sentence adds value without redundancy. Perfectly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and 100% schema coverage, the description adequately covers purpose, prerequisites, and a key behavioral trait. It does not explain return values or error conditions, but these are partially compensated by the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already explains the parameters. The description adds only the environment variable requirement and hard-delete note, which are behavioral rather than parameter-specific. Thus, no significant additional value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove a tag) and the resource (one or more contacts), making it distinct from the sibling tool 'civicrm_tag_contacts' which adds tags. The verb 'Remove' is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use this tool (to remove a tag) and mentions prerequisite environment variables. It lacks explicit guidance on when not to use it or alternatives, but the sibling list provides enough context for an AI agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the requirement for CIVICRM_ALLOW_WRITES=true, which is a behavioral trait. However, it does not mention what happens on success, error, or if the contact is missing. For an update tool, this is minimally adequate but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and includes an essential requirement without any unnecessary words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, 100% schema coverage, no annotations, and no output schema, the description is complete enough. It provides the purpose and a key prerequisite. It could mention return behavior but is not required per rules.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value beyond the schema by explaining dot-notation for custom fields in the 'values' parameter. This helps the agent understand how to structure nested data, which the schema alone does not fully clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and the resource 'a single CiviCRM contact by id'. It distinguishes from sibling tools like civicrm_create_contact and civicrm_get_contact by specifying 'update' and 'by id'. The requirement for CIVICRM_ALLOW_WRITES=true adds specific context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to update a contact by id) but does not explicitly mention when not to use or provide alternatives among the sibling tools. It is clear for its primary use case but lacks exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It mentions the optional substring filter, which is a key behavior. However, it does not explicitly state the read-only nature or that it returns entity names only. The description is sufficient but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the primary purpose and includes key details about extensions and filter. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one optional parameter, no output schema), the description fully covers what is needed. It is complete for its scope and leaves no ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with a description. The tool's description adds 'case-insensitive substring' context, which adds value beyond the schema's description. This helps the agent understand filtering behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all CiviCRM APIv4 entities including those from extensions, with an optional filter. It effectively distinguishes from sibling tools like civicrm_list_events which list specific types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exploring available entities but provides no explicit guidance on when to use vs alternatives like civicrm_describe_entity. No when-not or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool is disabled unless certain environment variables are set, and that writes and deletes have additional requirements. This alerts the agent to write and delete capabilities without explicitly stating 'this tool can modify data,' but the mention of 'deletes need CIVICRM_ALLOW_DELETES' implies destructive potential. It could add a caution about irreversible actions, but it is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loading the purpose first, then constraints, then guidance. Every sentence provides essential information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (generic API passthrough with no output schema), the description covers key aspects: what it does, its constraints, and a suggestion for pre-checking fields. It does not explain the return format or error handling, but since it is a passthrough, the response format is standard CiviCRM API response, which may be assumed. It is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 says 'Accepts entity + action + params,' which is a restatement of the required parameters. It does not add additional semantics beyond what the schema provides, such as explaining the structure or constraints of the params object. Thus, no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Generic APIv4 call. Accepts entity + action + params.' This clearly defines the tool's purpose as a generic passthrough to the CiviCRM APIv4, distinguishing it from the many sibling tools (e.g., civicrm_get_contact) that handle specific entities and actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it is a generic API call. It also gives when-not-to-use: 'Disabled unless CIVICRM_ALLOW_GENERIC_API=true; writes additionally need CIVICRM_ALLOW_WRITES and deletes need CIVICRM_ALLOW_DELETES.' It additionally suggests an alternative: 'Use civicrm_describe_entity first if unsure of field names.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the three pieces of information returned and implies non-destructive read-only behavior (sanity check). However, it does not explicitly state that it does not modify data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose 'Connectivity sanity check,' and contains no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description explains exactly what is returned, making it complete for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so baseline score is 4. The description does not need to add parameter information as the schema is fully covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: a connectivity sanity check that returns CiviCRM version, authenticated bot contact, and extension count. It uses a specific verb ('returns') and resource, distinguishing it from sibling tools that perform CRUD or other specific operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Run first when debugging auth or URL setup,' providing clear when-to-use guidance. It does not mention alternatives or exclusions, but the context of sibling tools is given and the advice is direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, description fully discloses behavioral traits: it is a read-only diagnostic tool that probes only read access, and does not perform writes. It could be slightly enhanced by noting that it doesn't modify state, but the current disclosure is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences that front-load the core purpose and usage guidance. Every sentence earns its place; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description adequately explains what the tool does and what it reveals (misconfigurations). It is complete for a diagnostic probe tool, though it could optionally mention that it does not list all readable entities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (0 params, schema coverage 100%). The description does not need to add parameter info, and the baseline is 4 for zero-param tools. No issues.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states it resolves the authenticated bot contact and probes readable entities, with specific verb+resource. It clearly distinguishes from sibling tools like civicrm_system_info or civicrm_get_contact by focusing on authentication and permissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Use this first when setting up the server' and lists specific misconfigurations it surfaces (wrong API key, missing permissions). Also notes it does not probe writes, guiding appropriate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![civicrm-mcp MCP server](https://glama.ai/mcp/servers/YogiAdhik/civicrm-mcp/badges/card.svg)](https://glama.ai/mcp/servers/YogiAdhik/civicrm-mcp)

Score Badge

Copy to your README.md:

[![civicrm-mcp MCP server](https://glama.ai/mcp/servers/YogiAdhik/civicrm-mcp/badges/score.svg)](https://glama.ai/mcp/servers/YogiAdhik/civicrm-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/YogiAdhik/civicrm-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server