Call the ChurchTools API

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.