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

It discloses behavior that annotations do not: the call is side-effect-free (it produces a plan, not a write), that an already-member person is an error, and where valid role ids originate. The annotations only carry readOnlyHint=false, destructiveHint=false and openWorldHint=true, which do not convey any of that. The one gap is that it never states whether the plan expires or whether re-calling 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.

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

Three short sentences with zero filler, and the highest-value fact (writes nothing, returns a plan) is front-loaded before the error condition and the role-id source. Nothing here restates the name or title.

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

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

For a six-parameter, no-output-schema tool, it covers the essentials: what the call returns, the failure mode, and where to get a required id. It is not fully complete because it does not connect the plan to ct_execute_plan, leaving the two-step plan/execute workflow implicit.

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

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

Schema description coverage is 83%, so the baseline is 3, and the description earns above that by explaining the provenance of groupTypeRoleId (GET /groups/{groupId}/roles via ct_api_request) and by framing groupId/personId in terms of the membership being created. It still says nothing about the optional comment, memberStartDate, or groupMemberStatus beyond what the schema already states.

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

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

It names a specific verb+resource (add a person to a group) but immediately qualifies the outcome with 'Writes nothing: returns a plan that adds the person', which is the single most important thing to know about this tool. It also distinguishes itself from ct_update_group_member for the already-a-member case, so an agent can separate it from siblings without opening any schema.

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

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

The description gives an explicit exclusion ('A person who is already a member is an error; use ct_update_group_member') and a prerequisite for role ids ('Role ids come from GET /groups/{groupId}/roles'). What it omits is the downstream step: it never mentions that the returned plan must be run through ct_execute_plan, which is the natural next action for a sibling tool.

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

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

With readOnlyHint=false and destructiveHint=false declared, the description supplies the crucial missing piece: writes are two-phase and return a preview plus a token rather than mutating anything, which reconciles why a DELETE-capable tool is marked non-destructive. It does not mention auth requirements (ct_login exists) or error behavior, keeping it at 4 rather than 5.

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

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

Four short sentences, front-loaded with the tool's scope, then the GET-versus-write branch, then the path constraint. Every sentence carries distinct information with no repetition of the schema.

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

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

For a fully generic API invoker with no output schema and 100% schema coverage, this covers the essential behavioral twist an agent could not infer from structured fields. It omits authentication expectations and how to discover valid operations, which the ct_login / ct_search_api / ct_get_operation siblings imply but are not referenced.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds constraints beyond the schema: the path must resolve to an operation in the spec with every template value filled in. That clarifies the concrete-path requirement more sharply than the schema's own wording.

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 (call any ChurchTools REST operation) and positions itself as the generic escape hatch among typed siblings like ct_get_person and ct_create_group. It also names the follow-up tool ct_execute_plan, so an agent can distinguish this from the concrete CRUD tools without opening any schema.

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

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

Clear context on when behavior differs: GET executes immediately while POST/PUT/PATCH/DELETE only produce a plan. It routes the agent to ct_execute_plan for the second phase. It does not explicitly say when to prefer a typed sibling over this generic tool, so it stops short of full when/when-not guidance.

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

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

Goes well beyond the annotations by disclosing the plan-based contract ('writes nothing'), the new id ChurchTools assigns, and how to observe the result via ct_get_event. It does not reconcile the tension with readOnlyHint=false or state that the plan must be applied by ct_execute_plan, which is the one behavioral detail an agent still needs.

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

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

Front-loads the key fact ('Writes nothing') and packs three useful clauses without filler. The semicolon-chained phrasing ('assigns one service assignment of an event ... to a ChurchTools person ... or to a name') is slightly dense to parse but nothing is wasted.

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

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

For a 6-parameter tool with no output schema, the description covers the return shape (a plan), the exclusivity of two optional params, and the sibling alternative. The notable omission is ct_execute_plan, the tool that actually applies the returned plan, which the agent needs to close the loop.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: personId and name are mutually exclusive and exactly one is required, and eventServiceId is clarified as one assignment inside the event's eventServices rather than a serviceId.

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 concrete effect (returns a plan assigning one event service assignment to a ChurchTools person or a name) and names the sibling it is not (ct_set_external_event_service). The agent can distinguish it from ct_get_event and ct_execute_plan without opening a schema.

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

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

Explicitly routes the agent: use the personId/name pair here, and use ct_set_external_event_service when the helper has no ChurchTools account. It also states the exclusivity rule ('give exactly one'), so the branch decision is fully specified.

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

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

The description asserts 'Writes nothing,' which directly conflicts with readOnlyHint=false, whose meaning is that the tool does modify its environment. This is a mirror of the calibration contradiction case (write verb vs readOnlyHint=true), so the description contradicts the structured annotation.

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

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

A single sentence with the key fact ('Writes nothing') front-loaded and no wasted clauses. It is efficient, though the trailing clause about repeatId is slightly compressed.

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 tool whose unusual output is a 'plan' and which has no output schema, the description should explain the plan's shape and how it is consumed. It says a plan is returned but not what it contains or what to do with it, leaving a meaningful gap.

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

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

Schema description coverage is 100%, so all six parameters are already documented, including repeatId's enum-like values in the fields description. The description only restates the single-vs-series distinction, adding no syntax or format detail beyond the schema.

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

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

The description states a specific verb and resource ('returns a plan to create an appointment') and clarifies the default-vs-series scope via repeatId. It implicitly separates itself from the actual write path, but never names the sibling that performs the write (e.g. ct_execute_plan), so sibling differentiation is implied rather than explicit.

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

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

By stating 'writes nothing: returns a plan,' it implies this is a first step in a two-phase flow, but it never says when to call this versus ct_execute_plan, nor that execution is required afterward. 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?

The description does add real value beyond annotations: it discloses the dry-run semantics and the duplicate-name refusal behavior. But it directly contradicts readOnlyHint=false by asserting 'Writes nothing', leaving the agent unsure whether state can change. The partial value is outweighed by the metadata conflict.

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

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

Two short sentences, with the most decision-relevant fact ('Writes nothing') front-loaded. The second sentence on duplicate-name handling also earns its place by preempting a likely failure mode.

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 should at least sketch the shape of the returned plan, since the agent likely needs to hand it to ct_execute_plan; it also says nothing about the nested 'fields' object or auth needs. It covers the key behavioral facts but leaves the return payload and the follow-up workflow unexplained.

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

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

Schema description coverage is 100% and every parameter is documented in the schema, including the groupStatusId value mapping (1 active, 2 pending, etc.). The description adds no parameter-level meaning of its own, so the baseline 3 for high coverage 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 — 'returns a plan to create a group' — and the leading 'Writes nothing' immediately disambiguates it from a real create like ct_create_person. It does not name any sibling or distinguish itself from the plan-execution counterpart, so it falls short of 5.

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

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

The dry-run framing implies the usage (call this to preview, then presumably execute elsewhere), which is the 'implied usage' level. However, it never names ct_execute_plan or any alternative, and gives no when-not condition, despite that being the single most useful routing fact for this tool.

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

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

The annotations declare readOnlyHint=false (i.e. the tool may modify state), while the description emphatically states 'Writes nothing' and only returns a plan. These are directly contradictory claims about whether the tool mutates the environment, so per the rubric this is an annotation contradiction.

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

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

The most surprising fact ('Writes nothing') is front-loaded and each sentence carries distinct information about duplicates, required fields, and the failure case. It is dense but not padded, and no sentence is wasted.

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

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

With no output schema, the description carries the return-value burden and does so by naming the duplicate listing and duplicatePersonId on rejection. Combined with the instance-dependent prerequisites, an agent has enough to call it correctly, though the handoff to execution is left implicit.

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

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

Schema coverage is only 50%, and the description compensates well: it explains that departmentIds come from the masterdata endpoint and that the free-form `fields` object may require statusId, campusId, or the privacyPolicyAgreement* keys depending on the instance — detail the schema's 'e.g. email, mobile, birthday' does not convey. It adds no meaning for firstName/lastName, which is why it is not a 5.

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

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

The description states a specific verb+resource — returning a *plan* to create a person — and explicitly scopes it with duplicate detection. The phrase 'Writes nothing: returns a plan' cleanly separates it from the actual creation/execution path (ct_execute_plan) and from ct_update_person, so an agent can tell what this tool is and is not.

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 real usage context: department ids must come from GET /person/masterdata via ct_api_request, and it explains when extra fields (statusId, campusId, privacy*) become mandatory per instance. It does not explicitly point the agent to ct_execute_plan as the next step to actually apply the plan, which is the one missing routing cue.

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

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

The description leads with 'Writes nothing: returns a plan,' but the annotations declare readOnlyHint=false, i.e. the structured data says this tool is not read-only while the prose says it changes nothing. The spec defines readOnlyHint as 'does not modify its environment,' so the two are directly inconsistent; the otherwise useful disclosure (series-wide effect, irreversibility, preview contents) is undercut by this mismatch.

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

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

Two tight sentences with the most important fact ('Writes nothing') front-loaded, followed by scope and irreversibility. No filler sentences; 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 two-parameter tool with no output schema, it covers the essentials: no writes, plan semantics, series scope, preview contents, and irreversibility. The one missing piece is how the returned plan is used (i.e., that ct_execute_plan runs it), which an agent must guess.

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

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

Schema description coverage is 100% and both ids are documented, including the notable note that one appointmentId covers every occurrence of a series. The description's 'for a series every occurrence goes' merely restates that schema note rather than adding syntax or format detail, so it lands at the baseline.

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

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

States a specific verb+resource (delete an appointment) and adds the crucial qualifier that it returns a plan rather than performing the delete, plus the series-wide scope. It does not name the sibling that consumes the plan (ct_execute_plan), so the two-phase workflow is only implied.

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 preview framing ('The preview shows the whole appointment') implies a preview-then-execute flow, but the description never says when to call this versus ct_execute_plan or ct_get_appointment, and gives no explicit exclusions. Usage is left to inference from the tool's shape.

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?

Adds real behavioral context beyond the annotations: no state is written, deletion is irreversible, and the cascade scope includes service assignments. The gaps are what the plan object contains and how it is later executed; note also a mild tension with readOnlyHint=false, since a tool that 'writes nothing' reads as read-only (destructiveHint=false is consistent, however).

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 with the most important fact — 'Writes nothing' — front-loaded, then scope, then the reason for the preview. Slightly compressed phrasing ('as a delete cannot be undone') but no wasted words.

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 return-value burden; it says only that a plan/preview is returned, without describing its structure or how the plan is consumed. For a plan-generating tool in a plan/execute pair, that follow-up step is the key missing piece.

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

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

Schema coverage is 100%, so both eventId and sendMail are already documented in the schema, and the description adds only the cascade scope ('with its service assignments'). It says nothing about sendMail or the effect of the mail option, so it does not exceed the schema 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 outcome: it returns a plan to delete an event plus its service assignments, and explicitly says it writes nothing — which corrects the misleading 'delete' in the name. It is distinguishable from ct_delete_appointment/ct_delete_group by resource, but it never points at ct_execute_plan as the follow-up, so the delete workflow's shape stays implicit.

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

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

Usage is only implied: 'the preview shows the whole event, as a delete cannot be undone' suggests this is the confirm-before-destroying step, but it never says when to call it versus ct_update_event or when to proceed to ct_execute_plan. No explicit when-not or alternative is given.

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

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

The description opens with 'Writes nothing', but the annotations declare readOnlyHint=false, i.e. the tool does have side effects / is not a pure read. This is a direct conflict between the narrative and the structured safety metadata. The irreversibility warning ('a delete cannot be undone') and the scope (group plus every membership) are useful, but per the rubric an annotation contradiction caps this dimension.

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 sentence, front-loaded with the most decision-relevant fact ('Writes nothing'), then the effect and the irreversibility. The clause 'to delete a group and with it every membership' is slightly tangled but 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?

For a one-parameter tool with no output schema, the description does cover the important facts: no writes on this call, full scope including memberships, and non-reversibility. It omits the essential next step in the workflow (the plan must later be executed), any plan lifetime/validity, and permission requirements, which an agent needs to act 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?

One parameter (groupId) with 100% schema description coverage, so the schema already carries the semantics and a baseline of 3 applies. The description adds no further parameter detail such as format constraints, id origin, or how to find a group id.

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 outcome: it returns a plan (preview) to delete a group together with all its memberships, which an agent can distinguish from the direct-mutation entry in its title. It is clear about what the call produces (a plan, not a deletion). Sibling differentiation is only implicit, however — nothing names ct_execute_plan or the alternative direct-removal route.

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: a reader infers this is the preview step of a plan-then-execute workflow because it 'writes nothing'. No explicit when-to-use, when-not-to-use, or named alternative (e.g. executing the plan afterwards, or removing a single member) is given.

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

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

Annotations only give readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description adds the crucial behavioral fact that no write occurs, that the preview shows the whole record, and that the underlying delete is irreversible. The 'Writes nothing' claim sits in tension with readOnlyHint=false, but it is consistent with destructiveHint=false and steers the agent correctly (more cautious, never less), and openWorld coverage is not explained.

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, front-loaded with the single most decision-relevant fact ('Writes nothing'), followed by the preview scope and the irreversibility rationale. Nothing is wasted and no key point 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?

For a one-parameter preview tool with no output schema, the description covers the return nature (a plan showing the whole record) and the irreversibility that motivates review. What is missing is the completion of the workflow — it never says the plan is executed elsewhere — but the core call semantics are otherwise sufficient.

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

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

There is a single parameter (personId) with 100% schema description coverage, so the schema already documents everything needed; the description adds nothing about the id format or any constraint. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb+resource: it returns a plan to delete a person, and explicitly says it writes nothing. That distinguishes it in spirit from the mutating siblings (ct_update_person, ct_delete_group) and from ct_execute_plan, though it never names ct_execute_plan as the follow-up and doesn't differentiate from siblings in so many words.

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

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

Usage is only implied: by saying it returns a plan rather than performing the delete, an agent can infer this is the two-phase preview step, but the description never states when to prefer it, nor that the plan must subsequently be handed to ct_execute_plan to actually delete the person. That missing handoff is the one piece of routing an agent most needs here.

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?

Adds substantial behavior beyond the annotations: the token is single-use with a 10-minute validity window, every guarded record is re-read first, and a detected change aborts the whole write. This all-or-nothing conflict semantics is exactly the kind of operational detail an agent needs before firing a destructive call.

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

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

Three short sentences, zero filler, and the gating precondition is front-loaded right after the purpose statement. Every clause earns its place.

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

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

For a one-parameter mutation tool with no output schema, the description covers purpose, precondition, token lifecycle, and failure behavior. It stops short of describing the success response or how to obtain a token in the first place, but both are largely implied by the preceding write-tool step.

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

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

Schema coverage is 100% and the single parameter is documented, so the baseline is 3. The description goes beyond 'The token of the plan to execute' by explaining the token's lifecycle — valid once, 10 minutes — which is real semantic value the schema does not carry.

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 ('Runs the writes') and resource ('a plan that a ChurchTools write tool returned'), which cleanly separates it from the sibling create/update/delete tools that produce the plan. An agent can tell this is the commit step of a two-phase write flow without opening any schema.

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

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

Gives an explicit precondition for invocation: 'Call it only after the user saw the preview and said yes.' That is a hard gating rule with no ambiguity, and no alternative tool competes for this job, so no exclusion list is needed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured fields. The description adds genuine behavioral context the annotations do not: the stored-vs-calculated date distinction and the fact that one id spans a whole series. It still says nothing about not-found handling or permissions.

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 no filler; the parenthetical is dense but carries real information about series semantics. It stays tight, though the parenthetical slightly burdens readability.

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

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

With no output schema, the description does useful work by describing what is returned (stored data plus calculated dates, series recurrence details). For a two-parameter read tool with read-only annotations, an agent has enough to call it correctly, though a brief note on lookup failures would complete the picture.

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 calendarId and appointmentId, including the note that one id covers every occurrence, are already fully documented by the schema. The description adds no parameter-level detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb (Shows) and resource (appointment) and even clarifies scope for a series (first occurrence, repeat pattern, exceptions, additional dates). It is clearly a singular fetch rather than a list, but it never names or differentiates from ct_list_appointments or the other appointment siblings, 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 implies usage by describing what a retrieval returns, and the 'for a series' clause hints that this is the tool for inspecting recurrence detail. But there is no explicit when-to-use versus ct_list_appointments, no prerequisite conditions, and no exclusions, 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine behavioral context beyond that by explaining the semantics of the isValid field ('false for a superseded or declined assignment') and clarifying that the returned id is the eventServiceId consumed by the service tools. It does not cover auth needs or limits, but that is less critical for a read tool.

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

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

A single front-loaded sentence with zero filler; the field list is dense but each item earns its place. It is compact and readable, though the parenthetical about eventServiceId slightly interrupts the enumeration flow.

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 must carry the return-value burden. It documents the service-assignment fields well but leaves 'the whole event' undefined — the event's own fields (title, dates, calendar) are never described — and it does not state prerequisites or the required eventId. Adequate but with clear gaps for a get-by-id tool.

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

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

Schema description coverage is 100% for the single eventId parameter (documented as 'The event's id'), so the schema already carries the parameter meaning. The description does not add syntax or constraints for eventId. Per the high-coverage rule, baseline 3 is 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 action and resource ('Shows the whole event with each service assignment') and enumerates the payload fields, so an agent knows it retrieves a single event by id along with its service assignments. It does not distinguish itself from siblings like ct_list_events or ct_get_appointment, so sibling differentiation is left to inference.

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

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

There is no explicit when-to-use or when-not-to-use guidance, no mention that eventId is required, and no routing to alternatives such as ct_list_events for enumeration or ct_get_appointment for appointment data. The only implicit signal is the singular 'the whole event', which suggests single-entity retrieval.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing that roles are NOT part of this response and must be fetched separately, but it says nothing about permissions, error behavior, or response shape beyond the field list.

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

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

Two tight sentences with the resource description front-loaded and the routing note second; the parenthetical field list is slightly verbose but functional. No wasted preamble.

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

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

For a read-only single-entity get with full schema coverage and no output schema, the description adequately compensates by enumerating returned fields and flagging the roles gap. Missing only the id-discovery path (search_groups) to be 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?

Only one parameter (groupId) with 100% schema description coverage, so the schema already carries the semantics. The description refers to the group's fields but adds no format, source, or lookup guidance for the id, 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 clear verb+resource ('Shows a group's...') and enumerates the returned fields (id, name, type, status, note, meeting time, settings), so an agent knows this is a single-group detail fetch. It does not explicitly contrast with ct_search_groups or ct_list_group_members, so sibling differentiation is only implied by the singular 'a group'.

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

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

Usage is implied (fetch details for a known groupId), and it helpfully routes the agent elsewhere for roles via GET /groups/{groupId}/roles (ct_api_request). However, it never states when to prefer this over ct_search_groups to resolve an id, nor any prerequisite conditions.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses two concrete behavioral limits: schemas are truncated below depth 4 and answers are capped at 20,000 characters. These are real operational constraints an agent needs when interpreting results. It still does not describe the response shape or error behavior, keeping it short of a 5.

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

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

Two sentences with zero filler. The core purpose leads, and the truncation caveats follow compactly in the same breath. Every clause carries information an agent needs.

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

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

There is no output schema, so the description must describe the return value, and it does ('parameters and the request body schema'), including the truncation limits. What is missing is any note on the response format or how the two inputs map to the returned document, but for a two-required-param introspection tool it is largely complete.

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

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

Schema description coverage is 100%, and the schema already explains that 'path' is listed by ct_search_api and that 'method' is the HTTP verb. The description adds no syntax or format detail 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 ('Shows') and resource ('parameters and the request body schema of one ChurchTools API operation'), leaving no ambiguity about what it returns. It is implicitly distinct from ct_search_api (which lists operations) because it targets 'one' operation, but the description itself never names that sibling to make the distinction explicit.

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

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

Usage must be inferred: an agent can figure out this is the detail-lookup counterpart to ct_search_api, but the description never says when to call it, when not to, or that ct_search_api should be used first to find a path. No prerequisites or exclusions 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=true and openWorldHint=true, so the safety profile is covered without the description. The only added context is 'the whole record', which is vague and does not disclose whether related data (groups, roles, contact details) is included or whether access is restricted by permissions.

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

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

One short sentence with no padding, and the core action is front-loaded. It is efficient, though efficiency here shades into under-specification rather than tight completeness.

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 what 'the whole record' contains, and it does not: no mention of returned fields, related entities, or error behavior for an invalid id. For a single-parameter read tool this leaves the agent guessing at the response.

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 personId parameter (integer, > 0), so the schema fully documents the input. The description adds nothing about the identifier's format or origin, 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?

The sentence identifies a specific resource (one person) and verb (shows/retrieves), and 'the whole record' hints at full retrieval rather than a subset. However, it never distinguishes itself from the sibling ct_search_persons or ct_get_group, so an agent must infer the boundary between 'get' and 'search' on its own.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to any alternative tool. With ct_search_persons and ct_list_group_members in the sibling set, the absence of routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description goes beyond them by disclosing the response shape and, usefully, the semantics of repeatId (0 = single occurrence, anything else = series), which is behavioral information an agent could not infer. Pagination and result-size limits are still unmentioned.

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

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

Two sentences, front-loaded with the core action and return fields, followed by a short disambiguation pointer. The first sentence is long, but each clause (field list, repeatId semantics) carries distinct information, so little is wasted.

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

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

With no output schema, the description correctly compensates by enumerating the returned fields and explaining repeatId. Combined with annotations covering read-only/open-world behavior, an agent has nearly everything needed; only pagination/limits and the meaning of the 'query' filter are left implicit.

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

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

Schema description coverage is 100%, so the schema already documents to, from, query, and calendar_ids (including the note that ChurchTools still includes the 'to' day). The description restates the calendar/date-range inputs at a high level without adding format or boundary detail beyond the schema, 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 ('Lists the occurrences of appointments'), the resource, and the scope (given calendars and date range), then enumerates the returned fields. It explicitly distinguishes itself from ct_get_appointment, which fetches 'the whole appointment', so an agent can separate the two 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?

Explicitly routes the agent to ct_get_appointment when the full appointment (not just occurrences) is needed, and the schema points to ct_list_calendars for obtaining calendar_ids. It does not address overlap with ct_list_events or state when-not to use this tool, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds substantive context beyond that: results are permission-scoped to calendars visible to the calling user, and the returned shape (id, name, visibility) is disclosed despite there being 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 clause-length sentence that front-loads the action and scope, then lists the payload. Every element earns its place with no filler or repetition of the title.

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

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

For a zero-parameter read tool with annotations covering safety and no output schema, the description supplies enough: scope, permission bound, and returned fields. Only minor gaps remain, such as ordering or whether calendars include ones merely subscribed to.

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 rule-of-thumb baseline of 4 applies. There is nothing parameter-wise for the description to compensate for, and the field list it provides describes the response rather than 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?

The description states a specific verb and resource ('Lists every calendar') and enumerates the returned fields (id, name, visibility). There is no calendar-related sibling among the tools, so differentiation is largely unnecessary, though it never explicitly positions itself against the other ct_list_* tools.

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

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

Usage is implied by the scope phrase 'every calendar the user can see', which tells the agent this is the unfiltered listing for calendars. It gives no explicit when-to-use/when-not guidance or prerequisites, but with zero parameters and no obvious alternative tool, the implied context is adequate.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and network scope are covered by structured data. The description's contribution is the enumeration of returned fields, which is useful but is data shape rather than behavior; it says nothing about result volume, pagination, or what happens with the schema-documented default range. Credit above baseline but not rich.

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

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

Two sentences, both front-loaded: capability and scope first, sibling routing second. The parenthetical field list is dense but earns its place because there is no output schema to carry that information.

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

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

With no output schema, the description voluntarily documents the return payload, which is exactly the gap a listing tool would otherwise leave. Combined with the annotation-covered safety profile and fully documented parameters, an agent has everything needed to call 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%, with detailed per-parameter docs including the ChurchTools default behavior when "to" is omitted. The description only says "in a date range" and adds no syntax, default, or interaction detail beyond the schema, 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?

"Lists the events in a date range" gives a specific verb and resource, and the description goes further by enumerating exactly which fields come back (id, name, start, end, canceled state, service assignments). It explicitly contrasts itself with ct_get_event, so an agent can separate it from the single-event sibling without reading 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?

Names the alternative tool and the condition that selects it: "Use ct_get_event for service names and the whole event." That is a concrete routing rule, not a vague hint, and the date-range scope in the first sentence tells the agent when this tool is the right one.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the returned field set, which matters because there is no output schema, but it says nothing about pagination behavior, result ordering, or empty-result handling despite the schema exposing page/limit.

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 with the core action front-loaded and zero padding. Nothing is repeated from the schema or annotations.

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 return fields, and all six parameters are self-documented in the schema. It is nearly complete for a read-only list tool; only pagination/ordering behavior is unaddressed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds one genuinely new detail by naming 'groupTypeRoleId' as the role identifier, which the schema does not spell out, but filtering/pagination semantics are left entirely to the schema.

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

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

States a specific verb ('Lists') and resource ('a group's members') and even enumerates the returned fields (person id, name, role id, membership status). It is clearly distinguishable from the write siblings (ct_add_group_member, ct_remove_group_member, ct_update_group_member), 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?

No when-to-use guidance, no prerequisites, and no routing advice among the many sibling list/search tools (ct_get_group, ct_search_persons, ct_search_groups). The purpose implies the context, but the agent gets no explicit condition for choosing this tool.

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

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

readOnlyHint and openWorldHint already establish the safety/world-access profile, lowering the bar. The description usefully adds what the operation actually returns (id, name, service group id, service group name) in the absence of an output schema; only missing auth/rate-limit context keeps it from 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?

A single front-loaded sentence with zero filler: verb first, then the resource, then the returned fields. Nothing could be removed without losing 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 zero-parameter read tool with annotations covering safety and an explicit list of returned fields, the description is essentially sufficient without an output schema. It omits ordering/pagination behavior, a minor gap for a tool claiming to list every service.

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 per the baseline a 4 applies; there is nothing for the description to disambiguate. The enumerated return fields are a bonus, but parameter semantics are not at issue here.

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 (Lists) and resource (services) and disambiguates the overloaded domain term with concrete examples (sermon, sound), so an agent won't confuse it with ct_list_calendars or ct_list_events. It does not explicitly name a sibling/alternative, which keeps it just 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?

"Lists every service" weakly implies no filtering is available, but there is no statement of when to use this versus the sibling search/list tools, no prerequisites, and no note about ordering or pagination behavior. The agent must infer usage entirely.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description's addition that 'a new call replaces the current session' is genuine behavioral disclosure about state side effects. The 2FA handling rule is also useful operational context. It still omits failure behavior for an invalid or expired code and any rate-limit/session-lifetime details.

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

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

Three short sentences, zero filler, and the primary action is front-loaded before the conditional 2FA rules and the session-replacement caveat. Every sentence carries information an agent needs.

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-optional-parameter login tool with no output schema, the description covers the key decisions (when to supply the code, session replacement) and annotations cover the mutation profile. What is missing is error/failure handling and confirmation of what a successful login returns or enables, which would round it out.

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% (the code parameter is fully documented, including its omission rule), so the baseline would be 3. The description adds real semantic value beyond the schema by instructing the agent to ask the user for the current code and never fabricate one, which is procedural meaning the pattern/format alone does not convey.

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

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

The description states a specific verb and resource ('Logs in with the configured user') and is unambiguous against the sibling list, which contains no other authentication tool. An agent can identify the operation immediately 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 gives explicit conditional guidance: pass the code when 2FA is enabled, omit it otherwise, and never guess the value. It does not, however, say when to call this versus siblings like ct_status (e.g., to check whether a session already exists), so the when-not side is only partly covered.

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

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

Beyond the annotations it discloses two non-obvious facts: the call performs no write and the returned preview contains the whole membership (not just a diff), which is exactly the behavioral context a preview tool needs. It leaves a tension unexplained with readOnlyHint=false, and says nothing about plan lifetime or how the plan is applied.

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 most important fact ('Writes nothing') front-loaded and zero padding. The trailing clause 'the preview shows the whole membership' is terse to the point of being slightly cryptic, which keeps it just short of ideal.

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

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

With no output schema, the description does describe the return value (a plan preview) at a high level, which is adequate for a 2-param tool. It is still incomplete on the essential workflow: how the plan is executed, whether it expires, and any permission prerequisites.

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

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

Schema description coverage is 100% with only two scalar id parameters, so the schema already fully documents groupId and personId. The description adds no format, constraint, or cross-parameter semantics beyond that 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+resource+scope: a plan that removes a given person from a given group, which is clearly separable from ct_add_group_member and ct_update_group_member. However it never names ct_execute_plan, so the agent is not told this is one half of a plan/execute pair.

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 word 'plan' and the front-loaded 'Writes nothing' imply this is the preview step that must be followed by an execution step, but no sibling is named and no when-to-use/when-not condition is given. An agent must infer that ct_execute_plan is the required follow-up.

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 declare readOnlyHint=true and openWorldHint=true, and the description is consistent with that, adding real context beyond the annotations: it returns operation metadata, not live API results, and must be chained through ct_get_operation before ct_api_request. It does not describe the result shape or ordering, so it is not fully self-contained.

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

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

Two tight sentences with no waste: the first states purpose and search scope, the second routes the agent to the correct follow-up tools. Nothing is buried 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?

There is no output schema, but the description conveys that the return is a set of API operations and that it is an entry point in a three-step workflow, which is what an agent needs. It stops short of noting anything about result ordering or ranking, a minor gap for a search tool.

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

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

Schema description coverage is 100% (baseline 3), and the description adds genuine meaning by enumerating the searchable fields (method, path, summary, tags) rather than just repeating the schema's 'Keywords, e.g. group members'. The limit parameter is left entirely to the schema, which already documents the 1-100 range.

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 (Finds) and resource (operations of the ChurchTools REST API) and specifies exactly which fields the keyword search spans: method, path, summary and tags. This clearly distinguishes it from the entity-specific search siblings like ct_search_persons and ct_search_groups, whose scope is data records rather than API operations.

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

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

Explicitly tells the agent when to use it ('anything no other tool covers') and then names the follow-up workflow: ct_get_operation for parameters and ct_api_request to call it. The fallback framing implicitly excludes cases where a dedicated sibling tool already applies.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds a genuinely useful behavioral trait beyond them: the result is a reduced projection (only id, name, group type id, status id). It stops short of mentioning pagination or result limits, which the schema covers separately.

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

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

Two tight sentences with zero filler; the capability statement comes first and the sibling routing second. Every clause earns its place.

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

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

With no output schema, the description usefully discloses what the response contains, which is the key missing structured information. Combined with the 100%-documented input schema and safety annotations, an agent has enough to call it correctly; pagination semantics are the only unaddressed item and are in the schema.

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

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

Schema description coverage is 100%, including the status id legend, so the schema already carries parameter meaning. The description only restates the filter dimensions at a high level (text, group type, status) and adds no syntax or combination behavior beyond it.

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 ('Finds') and resource ('groups') plus the three filter dimensions (text, group type, status). It also names the sibling ct_get_group and clarifies the boundary between the two, so the agent can separate them without opening schemas.

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

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

Explicitly routes the agent: use this for a lightweight search, use ct_get_group for the complete group. It gives a clear alternative and the condition selecting it, though it does not state exclusions (e.g. minimum query length or pagination expectations).

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 cover the read-only and open-world profile, so the bar is lower; the description still adds real value by disclosing the projected return shape (id, first/last name, email, status id) rather than the whole person record. It omits pagination behavior, though the schema's page/limit parameters largely cover 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?

Two sentences, both load-bearing: the first states what is searched, the second states what is returned and where to go for more. No filler and front-loaded with the capability.

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

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

With no output schema, the description usefully compensates by listing returned fields, and annotations carry the safety profile. Minor gap: no note on pagination/result-size limits despite page and limit parameters, but nothing essential for correct invocation 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 schema already documents all six parameters including defaults and status_id 0 semantics. The description's mention of text/email/status/archive maps onto query, email, status_ids and is_archived but adds no syntax or format detail 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 (Finds) and resource (persons) and enumerates the search axes (text, email, status, archive state). It also names the sibling ct_get_person and explains the distinct scope, so an agent can route between search and fetch 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?

Explicitly points to ct_get_person for the full record, giving a clear condition for choosing the alternative. It does not spell out when-not-to-use beyond that (e.g. bulk listing), but the routing guidance is concrete.

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

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

The description adds real behavioral context beyond the annotations: it writes nothing to the event, it returns a plan, and the resulting assignment gets a new id visible through ct_get_event. The 'writes nothing' phrasing sits in mild tension with readOnlyHint=false, but this is coherent because submitting a plan creates server-side plan state (which ct_execute_plan later applies) while the event itself is untouched.

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 most important safety fact ('Writes nothing'), then the alternative, then the result behavior. No filler and nothing repeated from the schema.

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

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

For a plan-producing mutation tool with no output schema and fully documented params, the description covers purpose, the alternative tool, and where the outcome is observed. The one meaningful gap is not stating that the returned plan is applied through ct_execute_plan, which leaves the plan lifecycle implicit.

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

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

Schema description coverage is 100%, so every parameter (eventId, eventServiceId, name, agreed, comment) is already documented, including the critical 'not the serviceId' clarification on eventServiceId. The description adds no format or constraint detail 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?

States a specific verb and resource: it 'returns a plan that fills one service assignment of an event ... with the name of a helper who has no ChurchTools account.' It immediately distinguishes itself from the sibling ct_assign_event_service by naming the condition (external vs. ChurchTools helper), so an agent can pick correctly 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?

Explicit routing rule: 'For a ChurchTools person use ct_assign_event_service' — a clear when-not with the named alternative. It also tells the agent where the result surfaces (ct_get_event). It omits the fact that the returned plan must be applied via ct_execute_plan, which is the other half of this tool's usage flow.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description goes beyond that by enumerating the concrete data surfaced (validity, login state, user, version, build, site name), which is meaningful disclosure given there is no output schema. It doesn't state whether authentication is required to call it, which is the one remaining behavioral gap.

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

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

A single sentence with no wasted words; the most decision-relevant information (configuration validity and login state) is front-loaded ahead of the version/build metadata.

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-parameter, read-only diagnostic with no output schema, the description adequately covers what comes back. It is only slightly short of complete because it doesn't indicate whether login is a precondition, which matters for a tool that reports login state.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline is 4. Coverage is 100% by definition and the description correctly introduces no phantom parameter discussion.

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 ('Shows') plus an enumerated set of resources: config validity, login state, logged-in user, version, build, and site name. That is far more concrete than a tautology and lets an agent distinguish it from data-fetching siblings like ct_get_person or ct_list_events. It does not explicitly contrast itself with ct_login, which is the one sibling an agent might confuse it 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. Notably, 'login state' overlaps conceptually with the ct_login sibling, and the description never clarifies whether this tool is the read-only way to check authentication versus actually logging in. The agent must infer the diagnostic purpose entirely.

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

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

Beyond the annotations, it discloses genuinely useful traits: no partial update is supported, so the plan resends the whole current appointment, the preview lists changed fields, and series edits apply to all occurrences. The 'writes nothing' phrasing sits in mild tension with readOnlyHint=false, but that hint is conservative and the destructiveHint=false value is consistent.

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

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

Three sentences, no waste, and the most decision-relevant fact ('Writes nothing') is front-loaded before the mechanics of full replacement and series scope.

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 explains what the plan preview contains (changed fields) and how it applies to series. The notable remaining gap is that it never tells the agent how to carry the plan forward (the execute-plan sibling), which matters for a two-phase mutation tool.

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

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

Schema coverage is already 86%, so the schema carries most parameter meaning. The description nevertheless adds a material parameter insight: because there is no partial update, the caller must supply the whole appointment rather than a sparse diff, which changes how every field is populated.

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

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

The description names a specific verb and resource ('returns a plan that changes the stored appointment') and immediately distinguishes the tool from writable siblings by stating 'Writes nothing.' It also clarifies the non-obvious scope that 'for a series the change applies to every occurrence,' so an agent can separate it from ct_delete_appointment or a plain read tool.

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

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

It gives clear context for when the tool is used (as the planning stage of an appointment change, not a direct write) and notes the full-replacement constraint that shapes the call. It does not, however, name the follow-up sibling (ct_execute_plan) needed to actually apply the plan, so the workflow routing is left implicit.

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

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

With annotations already declaring destructiveHint=false and openWorldHint=true, the description still adds real behavioral context: it writes nothing, it returns a plan rather than a mutated resource, and only changed fields are transmitted. There is a mild tension with readOnlyHint=false, but the statement is a deliberate clarification of a plan/apply pattern rather than a false claim about the operation; it stops short of explaining how the plan is consumed.

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

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

The critical fact ('Writes nothing') is front-loaded, and the single dense sentence contains no filler. The semicolon-chained clauses are information-packed but slightly heavy for the amount of content.

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 four-parameter plan tool with no output schema, the description covers what is mutated and what is not, but leaves the agent without any sense of the plan object's shape or the required follow-up step (executing the plan via the sibling ct_execute_plan). Adequate but with a clear gap for a tool whose whole purpose is producing an artifact.

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

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

Schema coverage is 100%, so the schema already documents all four parameters and the baseline would be 3. The description adds meaning beyond it by enumerating the three mutable fields (canceled, note, admins) and by stating the diff semantics that only changed fields are sent, which directly shapes how the agent should populate the call.

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 action and resource: returns a plan that changes an event's cancel state, note, or admins. It also bounds the field scope explicitly ('ChurchTools takes no other event field here'). It does not differentiate from siblings such as ct_execute_plan or ct_delete_event, so it falls short of a 5.

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

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

Usage is implied by the name and by the negative boundary statement that no other event field is accepted here, which steers the agent away from unsupported updates. However, there is no explicit when-to-use, no mention that the returned plan must subsequently be run through ct_execute_plan, and no comparison against ct_update_appointment or ct_delete_event.

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

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

The description asserts 'Writes nothing: returns a plan' (i.e. a side-effect-free, read-only operation), while the annotations explicitly declare readOnlyHint=false, meaning the tool may modify its environment. These are contradictory claims about the same property, so the behavioral disclosure and the structured data disagree — the precise situation the rubric says to score 1.

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 most important fact (no writes) followed by the patch/null semantics and field naming. Every clause carries information and there is no padding, though the second sentence packs three distinct rules together without separation.

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 nested-object planner with no output schema, the description covers the key semantics (no writes, patch-only-changed, null clears, flat field names). It does not describe what the returned plan looks like or how it is subsequently applied, and the readOnlyHint conflict leaves the tool's side-effect profile ambiguous.

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

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

Schema coverage is 100%, so the schema already documents groupId and fields (baseline 3). The description adds genuine meaning beyond it: fields are addressed by flat names (name, note, groupStatusId, visibility) and a null value clears a field, which the bare 'The fields to set' schema text does not convey.

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

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

The description states a specific action and resource: it returns a plan that patches only changed fields of a group. Combined with the title ('Plan a change to a ChurchTools group'), an agent can tell this is a dry-run planner rather than a mutator. It stops short of naming the relevant siblings (e.g. ct_execute_plan) to differentiate the plan/execute pair 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?

Usage is implied rather than stated: 'Writes nothing: returns a plan' signals this is a preview step that precedes execution, which is real implicit guidance. However, it never names an alternative (ct_execute_plan for applying the plan, or a direct update path) or states when a plan is preferable, so the when-to-use logic must be inferred.

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

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

Adds genuinely non-obvious behavior beyond the annotations: the call has no write effect ('Writes nothing'), it *returns a plan* rather than applying anything, and it patches only fields whose value actually changes (so an omitted field is not a clear, while an explicit null is). The diff-patch semantics is exactly the kind of detail an agent cannot recover from the schema. Minor tension with readOnlyHint=false, which is reconcilable if the generated plan/operation is itself persisted, but the description does not resolve it explicitly.

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

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

A single dense sentence, front-loaded with the most decision-relevant fact ('Writes nothing') and structured with a colon before the field list. Nothing is wasted, though the extreme terseness is what leaves the usage/workflow gap.

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

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

With no output schema, the description correctly fills that gap by stating the return value is a plan, and it explains the no-write and diff-only semantics. The one real omission is the downstream contract: nothing tells the agent how the returned plan is applied (presumably via ct_execute_plan), which matters for invoking the tool correctly as part of a workflow.

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

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

Schema description coverage is 100% and the schema already documents each field, including the enum meanings for groupMemberStatus and the 'null clears it' semantics. The description only recasts the fields in business language (role, status, comment, start/end date), which adds mild mapping value but no syntax or format detail beyond the schema. 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 action and scope: it returns a *plan* that patches a defined set of membership fields (role, status, comment, start/end date). That is far more precise than a restatement of the name and implies update-of-existing rather than add/remove. It stops short of naming the sibling tools it is meant to be chosen over (ct_add_group_member, ct_remove_group_member, ct_execute_plan), so it is clear but not sibling-differentiating.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the plan/execute handoff that this server clearly has (siblings ct_execute_plan and ct_get_operation). An agent is left to infer from the name alone that this is the tool for changing an existing membership, and to infer on its own what must be done with the returned plan.

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

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

The description adds real behavioral value beyond the annotations: it is a dry-run ('writes nothing'), it patches only changed fields, and null clears a field. However, this directly conflicts with the annotation readOnlyHint=false, which declares the tool is NOT read-only, creating an inconsistency about whether the operation has 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.

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

A single tight sentence, front-loaded with the most important trait ('Writes nothing'), and every clause (patch-only-changed, null-clears) earns its place. It is very terse for a tool with a nested object parameter and plan/execute workflow, but there is no wasted 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?

With no output schema, the description does explain the return value as a 'plan' and describes its patch semantics. But it omits important context for a planning tool: the plan's format and how it is applied (the ct_execute_plan sibling), plus any auth requirements. Adequate but with clear 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 coverage is 100%, so the baseline is 3, and the description adds meaning on top: the `fields` object semantics (only changed fields are patched, and a null value clears a field) go beyond the schema's terse 'The fields to set' description. This clarifies how to encode clearing vs. setting.

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 title 'Plan a change to a ChurchTools person' plus the description's 'returns a plan that patches only the fields whose value changes' give a specific verb (plan a patch) and resource (a person's fields). It implies a dry-run/preview distinct from the actual mutation performed by ct_execute_plan, but it never names that sibling, so differentiation is only implicit.

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

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

There is no explicit statement of when to use this tool, when not to, or which alternative to choose. The relationship to ct_execute_plan (i.e., that this produces a plan to be executed later) is only inferable from the word 'plan'; the agent gets no routing guidance.

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