ChurchSuite MCP by usefulapi

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

Annotations already mark this as readOnly=false, destructive=false, idempotent=false and openWorld=true, so the safety profile is covered; the description goes further and discloses note visibility to other ChurchSuite users, the private_to_me exception, that no message is sent to the contact, and that no edit/delete side effects occur. That's substantive behavioral context beyond the structured hints.

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-loaded with the WRITE classification and the core action, with supporting caveats and the endpoint in the same breath. Slight redundancy in restating private_to_me semantics already documented in the schema keeps it from being maximally economical.

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 4-parameter mutation tool with no output schema, the description covers operation class, side-effect boundaries, visibility semantics, and the underlying endpoint. It omits what the call returns (e.g., the created note or its id) and any permission prerequisite, which would be the remaining gaps for an agent.

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; the description adds real meaning for private_to_me by framing it as visibility to other users versus only the API user, which is the consequence an agent needs to reason about before setting the flag. It adds nothing extra for content, contact_id, or pinned, so it sits modestly above 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 resource ('add a new note to a contact's record') and prefixes it with 'WRITE:' so the operation class is unambiguous. An agent can immediately distinguish this from the read-side sibling churchsuite_list_contact_notes 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?

'Only adds a note: never edits or deletes anything, sends nothing to the contact' clearly bounds when this tool is and isn't the right choice, which is the main routing risk for a note-creation tool. It stops short of naming an explicit alternative (e.g., use list_contact_notes to read existing notes), so it's strong context rather than a full when/when-not/alternative triad.

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 the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description adds genuinely non-structured context: the exact payload contents and the explicit exclusion of billing and data-protection contact details, plus the underlying endpoint.

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

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

Front-loaded with the payload contents and a routing hint, with no padding. The trailing "API: GET /account/info" is slightly redundant metadata but harmless and short.

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 carries the burden of describing returns — and it does so by enumerating the returned fields and noting what is excluded. For a zero-parameter read tool this is 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?

The tool takes zero parameters, so the baseline is 4; there is nothing to document and the description does not mislead about inputs.

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

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

States a specific verb+resource (get the church's account summary) and enumerates the exact fields returned (name, id, subdomain, time zone, currency, language, first day of week), including an explicit exclusion note. This clearly distinguishes it from the resource-specific siblings like get_contact or get_event.

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?

"A good first call" gives the agent clear context for when this tool is appropriate (early in a workflow to orient on the account). It does not name alternatives or conditions for when-not to use it, so it stops 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, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds value beyond that by flagging medical, doctor_details and additional_needs as sensitive fields gated behind an opt-in flag, and by naming the underlying endpoint (GET /children/children/{id}). It does not discuss permission scope or error behavior, so not 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 what the call returns, then the sensitive-field caveat, then the endpoint. No filler and nothing that duplicates structured data unnecessarily.

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

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

With no output schema, the description carries the burden of describing the response and does so by enumerating the returned field groups, plus explicitly carving out the conditionally-returned medical fields. For a two-parameter single-record read whose annotations already cover the safety profile, nothing an agent needs is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents both params. The description goes slightly beyond the schema by emphasizing that medical fields are sensitive and are only surfaced via include_medical: true, reinforcing the opt-in semantics rather than merely restating them.

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 ('Get one child by id') and immediately enumerates the returned surface (names, DOB, school, contact details, custom fields, consents, sites, status), which is exactly what separates it from the sibling churchsuite_list_children. An agent can tell single-record retrieval from list retrieval 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?

The 'by id' framing makes the precondition clear (you must already have a child_id), and it gives an explicit conditional for the sensitive path: medical/additional-needs fields 'only with include_medical: true'. It stops short of naming the alternative ('use list_children to discover ids') or any when-not condition, 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?

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine value beyond that by disclosing the breadth of returned data (custom fields, communication preferences, sites, status) and the underlying endpoint, which no structured field provides since there is no output schema.

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

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

A single front-loaded sentence with the purpose first, followed by the returned-field inventory and endpoint. It is efficient, though the trailing 'API: GET /addressbook/contacts/{id}' is arguably redundant for an agent that already has the tool name and 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 one-parameter read tool with annotations covering safety and no output schema, the description compensates well by listing what comes back. It stops short of describing the shape of those fields (nesting, formats) or error behavior for an unknown id, so it is strong but not fully complete.

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

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

Schema description coverage is 100% for the single contact_id parameter, so the schema already documents type, range and meaning. 'By id' adds no syntax or format detail beyond what the schema states; 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 and resource ('Get one Address Book contact by id') and enumerates the returned fields, which distinguishes it from list_contacts and get_child. An agent can identify this as the single-record lookup without opening the schema.

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

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

'By id' implies this is a lookup requiring an already-known contact id, which is useful implied usage. However, there is no explicit when-to-use guidance, no mention of list_contacts as the way to obtain ids, and no exclusions relative to sibling retrieval tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the returned field set (times, status, category, location, description, visibility, sign-up options), which is genuinely useful given no output schema, but says nothing about auth requirements, pagination, or error behavior for unknown ids.

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

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

Two short sentences, front-loaded with the operation and resource, then the payload preview and endpoint. No filler or restated boilerplate.

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

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

For a single-parameter read with full annotation coverage and no output schema, the description does enough: it enumerates the returned fields so the agent knows what it gets back. Minor omissions (failure mode for bad ids, rate/auth context) keep it from a 5.

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

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

Schema description coverage is 100% and the single parameter already documents itself as 'The event's numeric id.' The description's 'by id' adds nothing beyond the schema, 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 ('Get one calendar event') and scopes it with 'by id', which implicitly separates it from the sibling list_events. It never names a sibling or alternative explicitly, so the differentiation is inferable 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 'one ... by id' phrasing implies the use case (retrieve a single known event rather than enumerate), but there is no explicit when-to-use guidance, prerequisites, or pointer to list_events for enumeration. Usage 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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the set of fields returned, but says nothing about auth requirements, permissions, rate limits, or error behavior for an invalid id.

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

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

Two sentences, zero filler, front-loaded with the core action and the returned fields, with the API endpoint appended as useful reference.

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

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

With no output schema, the description usefully enumerates the returned content, which is what an agent needs to judge applicability. Only permission/error behavior is left unspecified, a minor gap for a simple read-only lookup.

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

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

Schema description coverage is 100% and the single parameter (group_id, positive integer) is fully documented in the schema. The description only restates 'by id' without adding format or edge-case semantics, 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 ('Get') and resource ('one small group by id') and enumerates the content returned (schedule, location, description, custom fields, sign-up options, sites), which cleanly separates it from the sibling churchsuite_list_small_groups.

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 singular 'one small group by id' implicitly distinguishes this from churchsuite_list_small_groups and churchsuite_list_small_group_members, but there is no explicit when-to-use statement, no prerequisite guidance, and no named alternative.

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

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

Annotations already declare readOnly/idempotent/openWorld/destructive=false, so the safety profile is covered. The description adds behavior not in the annotations: results are sorted by date, the shape of a record, and the underlying endpoint GET /attendance/records. Pagination behavior is left to the schema, but the added context is genuinely useful.

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 first front-loads what is returned and how it is sorted, the second covers filters and the endpoint. No filler and nothing buried.

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

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

There is no output schema, so the description correctly compensates by naming the returned fields and sort order. Filters are summarized adequately; the only gap is that pagination parameters go unmentioned in prose, though the schema covers them fully.

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. The description restates the filter dimensions (gathering, weekday, date window) and the YYYY-MM-DD format, but this duplicates what the schema already documents and omits the page/per_page pagination parameters entirely.

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

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

States a precise verb+resource ('List attendance records') and immediately defines what a record contains (headcount per gathering/date, totals, notes), plus the sort order. No sibling tool covers attendance, so the scope is unambiguous and an agent can select it without opening the schema.

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

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

Enumerates the three filter axes (gathering, weekday, date window), which tells the agent when this tool fits. It stops short of stating exclusions or prerequisites (e.g., no attendance tool alternative exists, so there is nothing to route away from), but the usage context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: sensitive medical, medical_short, doctor_details and additional_needs fields are omitted unless include_medical is true, and it names the underlying endpoint.

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: purpose/fields, the sensitive-field caveat, and the endpoint. The sensitive-field warning is placed prominently, and no sentence is redundant filler.

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

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

With no output schema and nine optional parameters, the description compensates by listing the fields returned and flagging the medical-data opt-in. An agent has enough to call it correctly, though pagination/return envelope behavior is left to the schema.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema (including the include_medical semantics). The description largely restates that filtering/field behavior rather than adding syntax or format details 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?

The description gives a specific verb ("Search or list") and resource ("children in the Children module") and enumerates the returned fields (name, DOB, school year, contact details, sites, status, consent flags). It is clearly distinguishable from the singular get_child sibling by being a list/search operation, though it never names an alternative explicitly.

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

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

There is no statement of when to use this tool versus siblings such as get_child (single record) or list_children_groups. "Search or list" hints at two modes but gives no conditions, prerequisites, or 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds value by enumerating the returned fields (id, name, entry age, check-in capacity/ratio, status) and the underlying endpoint, but says nothing about pagination behavior or result ordering. With annotations carrying the behavioral burden, a 3 is appropriate.

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

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

One compact sentence with the resource and returned fields front-loaded, followed by the API endpoint. Every clause contributes; the endpoint reference is slightly redundant for an agent but harmless.

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

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

For a read-only list endpoint whose annotations cover safety and whose schema covers most parameters, the description suffices. The absence of an output schema is partially offset by the enumerated return fields, though pagination semantics remain implicit.

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

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

Schema coverage is 75% and the description mentions no parameters at all. Notably, the 'status' enum has no schema description, and the description's phrase 'status' as a returned field doesn't clarify the filter. Baseline 3 is warranted since the schema largely documents q, page and per_page.

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

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

States a specific verb (list) and resource (Children module's groups) and clarifies the domain with 'classes/age groups', so an agent can distinguish it from list_children and list_small_groups. It doesn't explicitly name those siblings, but the resource is unambiguous.

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

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

No guidance on when to use this versus siblings like list_children or list_small_groups, and no prerequisites or exclusions. Usage is only implied by the tool name and resource.

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 the safe read profile (readOnlyHint, idempotentHint, destructiveHint false), so the bar is lower. The description adds genuinely new behavioral context beyond them: the 'pinned first' ordering and the composition of each note (who wrote it and when), which the agent would not otherwise know.

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

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

One front-loaded sentence carries purpose, return fields and sort order, followed by the API endpoint on a separate clause. No filler; every element earns its place.

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

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

No output schema exists, yet the description compensates by naming the returned fields and ordering, which is exactly what an agent needs. Only pagination behavior for a potentially long notes list is left unmentioned.

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

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

Schema description coverage is 100% and the single contact_id parameter is fully documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 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 (List) and resource (contact notes), and enumerates the returned fields (content, pinned, visibility, author, timestamp), which sharply distinguishes it from the write-side sibling churchsuite_add_contact_note. An agent can identify the operation 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?

The description implies its usage ('notes on a contact') but never states when to prefer it over alternatives or any prerequisites for reading a contact's notes. Usage is inferable from the resource, not spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds only a personal-data caution and the underlying endpoint; it says nothing about pagination or the sensitivity of returned records beyond that.

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, front-loaded with purpose before the privacy note and endpoint. The API path is marginal value but does not bloat the text.

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 7-parameter list tool with full schema coverage and no output schema, the description covers purpose, scope and privacy adequately. It leaves the return shape and pagination implicit, which the schema partly supplies.

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 (q, page, status, tag_ids, order_by, per_page, site_ids) is already documented. The description's parenthetical field list maps loosely to the filter parameters but adds no syntax or semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb pair (search/list) and resource (adult contacts in the Address Book), and enumerates the fields it exposes (name, contact details, address, sites, status, tags). The 'adult' qualifier usefully distinguishes it from list_children, though it does not name get_contact as the alternative for single-record fetches.

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

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

Implies usage ('search or list') and adds a privacy directive ('ask only for what you need'), but does not state when to prefer this over churchsuite_get_contact for a single record or how it differs from sibling list tools such as list_contact_tags.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds the HTTP endpoint and the shape of each returned record, but says nothing about pagination limits or the result-set size behavior beyond what the schema's page/per_page fields imply.

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 it lists, how to use the result, and the backing endpoint. No filler, and the purpose is front-loaded before the workflow hint.

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

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

With no output schema, the description usefully enumerates the returned fields and the endpoint, and the schema covers pagination and filtering. It stops short of describing total counts, response envelope, or rate limits, which a no-output-schema list tool could reasonably mention.

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 (q, page, order_by, per_page) are already documented in the schema, including the enum for order_by and the next_page usage note. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

Specific verb+resource ("List Address Book tags"), enumerates the returned fields (id, name, category, smart tag), and anchors the operation with the underlying API call GET /addressbook/tags. An agent can distinguish this from list_contacts and the other list_* siblings without opening the schema.

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

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

It explains a downstream workflow — feed the tag id into list_contacts as tag_ids — which implies why you'd call this. But it gives no explicit when-to-use vs. alternatives, no prerequisites, and no note on how this list relates to the other tag/contact listing tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds the underlying API path (GET /calendar/categories), a small bonus, but says nothing about pagination behavior or rate limits. A 3 is appropriate given annotations carry the safety profile.

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

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

Three short sentences, zero filler, with the purpose and returned fields front-loaded and the cross-tool usage note and API path trailing. Every sentence earns its place.

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

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

With no output schema, the description helpfully enumerates the returned fields, and pagination is handled by the schema's page/per_page descriptions. It is nearly complete, missing only a note that results are paginated when many categories exist.

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 75%, with q, page and per_page documented in the schema. The description offers no additional filter semantics and only mentions 'status' as a returned field, not as the active/archived filter the schema exposes. 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 calendar categories') and enumerates the returned fields (id, name, colour, status). The context link to list_events makes it clearly distinguishable from sibling list tools such as list_events or list_contact_tags.

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

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

The line 'Use the ids as category_ids in list_events' gives downstream usage context, but it never states when to call this tool versus alternatives (e.g. searching events directly, or filtering by status/archived categories). Usage is implied rather than prescribed.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds the endpoint path and the returned field set, which is useful context, but says nothing about pagination behavior, rate limits, or result envelope beyond what the schema's page/per_page descriptions imply.

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 the tool lists, then the date-window hint, then the API path. Every sentence carries information and none is filler.

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

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

With no output schema, the description compensates well by enumerating the returned fields (name, start/end, status, category, location, description, sign-up options, sites). It does not explain pagination flow itself, though the schema's page/per_page descriptions cover that, so the gap is minor.

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 90%, so nearly every parameter is already documented in the schema. The description restates the date-window parameters and their YYYY-MM-DD format, which the schema already provides, adding no new semantic detail. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('List calendar events') and enumerates the fields returned, plus the underlying API endpoint (GET /calendar/events). It is clearly distinct from the singular get_event and from list_event_categories, though it never names a sibling explicitly to reinforce that distinction.

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

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

It gives usage guidance for a parameter ('Use starts_after/starts_before for a date window') but no guidance on when to choose this tool over alternatives such as get_event or list_event_categories. Usage is implied by naming, not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the concrete API endpoint (GET /attendance/gatherings) and the returned fields (id, name, sites, status), which is useful since there is no output schema, but says nothing about pagination limits or rate behavior.

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

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

A single compact sentence with the resource definition front-loaded, followed by the API route. No wasted prose, though the endpoint line is somewhat redundant for an MCP caller.

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 five optional parameters and no output schema, the description partially compensates by naming the returned fields, but it omits pagination semantics and any explanation of how status, q, or site_ids shape the result set. Adequate but with real gaps.

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

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

Schema description coverage is 80% and the schema documents q, page, per_page and site_ids well, so the baseline is 3 even though the description adds no per-parameter detail. Note the status enum is undocumented in the schema and the description does not compensate.

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

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

States a specific verb (List) and resource (Attendance module's gatherings), and defines gatherings as services/meetings whose attendance is counted, which separates it from the sibling list_attendance_records. It does not name that sibling explicitly, so it stops short of a 5.

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

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

The description gives no when-to-use guidance, no conditions that select this tool over list_attendance_records or list_sites, and no note on filtering by status or site. The agent must infer usage entirely from the name and 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond them by declaring the result shape and explicitly scoping out donor/donation/amount data, though it says nothing about pagination or result limits.

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

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

Three tight clauses: purpose, field list, scope exclusion, endpoint. Front-loaded with the core action and zero filler sentences.

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

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

With no output schema, the description carries the burden of describing return contents and does so explicitly (field list plus Gift Aid / Donate flags). Pagination mechanics live in the schema, so nothing an agent needs to call this 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 75% (q, page, per_page documented; status enum undocumented). The description adds no parameter-level meaning, only field names of the returned records, so it neither compensates for the status gap nor improves on 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 and resource ('List the church's giving funds') and enumerates the returned fields (id, name, description, Gift Aid flags, Donate visibility, status). The 'Funds only: no donors, donations or amounts' clause draws a hard boundary that no sibling listing tool can confuse with.

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

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

The negative scope ('Funds only: no donors, donations or amounts') usefully tells the agent what this tool will not return, but there is no explicit when-to-use trigger or named alternative. Usage is implied by the resource name rather than stated as a routing rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by naming the underlying endpoint (GET /rotas/ministries) and enumerating the fields returned, which matters because no output schema exists; it does not contradict any annotation.

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

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

One sentence plus a short API note, with the verb and resource front-loaded and the field list compressed into a single parenthetical. Nothing is padded or repeated.

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

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

With no output schema, the description usefully compensates by enumerating returned fields, and the schema fully covers inputs and pagination. The only real gap is that filtering capability goes unmentioned in prose, but an agent can still call it correctly from the schema alone.

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

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

Schema description coverage is 100%, so all six parameters (q, ids, page, per_page, site_ids, statuses) are fully documented in the schema, including pagination semantics and next_page usage. The description adds nothing parameter-specific, 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 — 'List the Rotas module's ministries' — and even parenthetically instantiates it (worship team, welcome team), so an agent knows exactly what objects come back. It stops short of differentiating from close siblings such as churchsuite_list_ministry_members and churchsuite_list_ministry_teams, which is what a 5 would require.

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

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

There is no when-to-use statement, no note that the tool supports fuzzy search / id / site / status filtering, and no routing to alternative tools. The description reads as a pure definition rather than guidance, leaving the agent to discover filtering behavior only by opening 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. Beyond that the description adds real value by naming the underlying endpoint (GET /rotas/ministry_members) and clarifying that the 'person' field may be a contact or child id, which is non-obvious behavior for this data shape.

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

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

Two tight sentences plus an endpoint line: purpose and payload first, then the follow-up lookup hint, then the API path. Nothing is padded and nothing important is buried.

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

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

With no output schema, the description carries the burden of explaining returns, and it does list the key fields an agent needs to interpret results, while pagination is fully handled by the schema's next_page hint. A quick note on default ordering or result volume would make it fully self-sufficient, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100% (page, order_by, per_page, role_ids, team_ids, ministry_ids are all documented in-schema), so the baseline is 3. The description restates the id-based filtering fields but adds no syntax, defaulting, or combination semantics beyond what the schema already supplies.

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

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

States a specific verb and resource ('List who serves in rota ministries') and enumerates the return payload (ministry id, team id, person id, role ids), which cleanly separates it from sibling listers like list_ministries and list_ministry_teams that cover the ministry/team entities themselves rather than their 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?

It gives actionable workflow context: resolve the returned person id via get_contact or get_child, and it implicitly frames the tool as the membership-lookup step. It stops short of explicit when-not guidance or naming a sibling alternative, so it is clear context without 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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds the REST endpoint and the shape of each returned row, which is genuine extra context given there is no output schema, but nothing about pagination behaviour or filter interaction.

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

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

Two short sentences, front-loaded with the resource and scoped with the parent domain, then the endpoint. Every clause carries information and there is no padding.

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

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

For a read-only list tool with a fully described four-parameter schema and rich annotations, the definition covers purpose, scope and returned fields adequately. It could still note that results are paginated and that the id filters are optional, but nothing essential to a correct call 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%: page, per_page, team_ids and ministry_ids all carry their own constraints and descriptions. The description adds no parameter-level meaning beyond that, so the baseline 3 applies even though the filter semantics are well documented in 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 and resource ('List the teams inside rota ministries') and even enumerates the returned fields (id, ministry id, name, order), which separates it from churchsuite_list_ministries and churchsuite_list_ministry_members. It falls short of a 5 because it never explicitly contrasts itself with those nearest 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 phrase 'inside rota ministries' implies the domain scope, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. use list_ministries to enumerate the parent ministries first). An agent must infer routing from the name alone.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the underlying endpoint (GET /planning/plan_items) and the OPTIONAL-fields returned, but says nothing about pagination behavior beyond what the schema documents, permissions, or rate limits.

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

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

One tight sentence plus a short API reference; the returned-field list is front-loaded usefully. The endpoint echo is slightly redundant but costs almost nothing.

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

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

With no output schema, the description usefully enumerates the returned item fields (type, name, arrangement, duration, start time, notes, people), which compensates for the missing return documentation. Combined with a 100%-covered input schema and annotations, an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so page, per_page, order_by, and plan_ids are all fully documented in the schema with enums, bounds, and defaults. The description adds no parameter syntax or constraint beyond that, making the baseline 3 correct.

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

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

States a specific verb and resource ('List the running order of one or more service plans') and enumerates the item fields returned, which distinguishes it from the broader list_service_plans sibling. It never names that sibling explicitly, so the plan-vs-item distinction relies on inference from the parenthetical.

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

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

Usage is only implied: the schema note that plan_ids come 'from list_service_plans' hints at the workflow, and 'one or more' hints at batching. There is no explicit when-to-use, when-not-to-use, or stated alternative for retrieving item data another way.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds little beyond module provenance and the underlying REST endpoint; it does not mention pagination behavior or result volume, so it is adequate but not value-adding.

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

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

Two short, front-loaded sentences with no filler. The trailing 'API: GET /planning/plans' restates a transport detail an agent cannot act on, which is the only wasted fragment.

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 eight optional parameters, no required params and no output schema, the description helpfully lists the main returned fields, which partly compensates for the missing output schema. However it omits how the filters combine, default paging size behavior, and any pairing rules for the date bounds.

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 88% (only 'status' lacks a description), so the schema does the heavy lifting and the baseline of 3 applies. The description's parenthetical enumerates return fields rather than parameters, so it adds nothing to filter semantics such as date-range pairing of starts_after/starts_before.

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

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

States a specific verb (List) and resource (service plans) and locates it in the 'Planning module', plus enumerates the fields returned. The sibling list_plan_items is a different resource, but the description never explicitly distinguishes itself from it, so it stops short of a 5.

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

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

There is no indication of when to call this versus list_plan_items, list_events, or list_gatherings, and no prerequisites or exclusions are mentioned. Usage is only implied by the tool's name and the available filters.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety and repeatability profile is fully covered. The description contributes the API endpoint (GET /account/sites) and the downstream-filtering semantics, but says nothing about pagination, auth requirements, or result limits.

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

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

Three short sentences, front-loaded with purpose, followed by the useful downstream context and the API path. No filler, and the most decision-relevant information (what it lists, what the ids are good for) comes first.

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

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

For a zero-required-parameter list tool with no output schema, the description compensates by enumerating the returned fields and explaining the practical use of the result. Combined with rich annotations, an agent has everything needed to call and use this correctly.

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

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

Schema description coverage is 100% for the single 'ids' parameter, which already documents the numeric ChurchSuite ids and the 100-item cap. The description adds only indirect meaning by noting that site ids are reused as filters elsewhere; it gives no format or edge-case guidance for this parameter beyond the schema. Baseline 3 applies.

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

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

States a specific verb (List) and resource (church's sites), then disambiguates the resource with a parenthetical glossary ('campuses/congregations') and enumerates the returned fields (id, name, initials, address). An agent can tell exactly what this returns and can distinguish it from the many other churchsuite_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?

Explains why the tool matters: 'Site ids filter contacts, children, groups, events and plans,' which tells the agent to call this first when it needs site ids for downstream filtering. It does not name a specific alternative or state when-not to use it, 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the underlying API endpoint (GET /smallgroups/members) but says nothing about pagination limits or auth, so it is only marginally additive beyond the annotations.

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

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

Three compact sentences: purpose and return fields first, then filter routing, then API endpoint. No filler, and the most decision-relevant information is front-loaded.

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

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

With no output schema, the description usefully enumerates the returned fields and explains filter modes, which is what an agent needs to call this correctly. Pagination is covered by schema descriptions, so nothing critical is missing, though response shape is only sketched.

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 88%, so per-parameter docs largely exist. However, the description adds non-obvious filter semantics: group_ids returns a group's members while contact_ids/child_ids return a person's groups — a dual-mode behavior not evident from the schemas alone. The status/role_id filters are left 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 and resource ('List small group memberships') and enumerates the returned fields (group id, person = contact or child id, status, role ids, joined date). This clearly separates it from siblings like list_small_groups or list_ministry_members, which cover different entities.

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 routing: filter by group for a group's members, by contact/child for a person's groups, and points to get_contact/get_child for id lookup. It lacks any 'when not to use' or exclusion guidance, but the bidirectional filter guidance is strong.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without description help. The description adds the endpoint path and the shape of a returned group, which is modest extra context, but says nothing about pagination behavior, result limits, or whether the default view filters anything out.

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

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

Two sentences, zero preamble, with the core action and its domain synonyms front-loaded before the endpoint footnote. The long parenthetical of returned fields is dense but scannable. Structurally efficient; nothing is wasted, though the field list could be trimmed without much loss.

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

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

With no output schema, the description usefully compensates by naming the fields a group contains, and every one of the nine optional filters is fully documented in the schema. Combined with annotations that carry the read-only/idempotent profile, an agent has enough to call this correctly; only return-envelope concerns like pagination metadata or empty-result behavior are unaddressed.

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

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

Schema description coverage is 89%, so the schema already documents q, days, page, view, order_by, per_page, site_ids and cluster_ids in detail; the description adds no parameter-level meaning on top of that. The parenthetical list of fields maps loosely to the frequency enum but does not explain that parameter, whose schema entry has no description at all.

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 small groups") and disambiguates the domain by naming synonyms ("home groups/life groups"), plus the underlying endpoint GET /smallgroups/groups. It also enumerates the fields each group carries, so an agent knows exactly what a result represents. It stops short of explicitly contrasting with the singular sibling churchsuite_get_small_group, which is the only remaining differentiator an agent must infer from naming.

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 rather than stated: the plural resource name plus the filter set (days, view, frequency, site_ids, cluster_ids) makes it clear this is the browse/filter tool, but the description never says when to prefer it over churchsuite_get_small_group or churchsuite_list_small_group_members. No exclusions, prerequisites, or alternative routing are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds the API path and the shape of the returned records, which is useful given no output schema, but it says nothing about pagination behavior, rate limits, or empty-result behavior.

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

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

Three short sentences, front-loaded with the primary purpose followed by filtering dimensions and the API reference. No filler and no redundancy; every clause carries information.

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

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

For a read-only, fully-optional-parameter list tool with no output schema, the description covers what is returned and how to narrow it, which is sufficient to call it correctly. Minor gaps around pagination and result ordering are handled by the schema, so completeness is good.

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 (page, order_by, per_page, child_ids, contact_ids, ministry_ids, starts_after, starts_before) is already documented in the schema. The description restates the person/ministry/date filtering dimensions at a high level but adds no syntax, id-format, or boundary detail beyond what the schema provides, which matches the baseline for high coverage.

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

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

States a specific verb (List) plus resource (rota unavailability) and even enumerates the returned fields (person, description, start/end) and the underlying endpoint. It is unambiguous, though it does not explicitly differentiate itself from any sibling because none of the listed siblings cover rota/unavailability data.

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 implies its usage via "Filter by person, ministry or a date window," which tells an agent the three axes available for narrowing results. However, it never states when to reach for this tool versus alternatives, nor any exclusions or prerequisites, so guidance is only implied.

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