Breeze ChMS MCP by usefulapi

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

Annotations supply only destructiveHint=true and a title, so the description does real work here: it discloses the write nature, the Unix-seconds time convention, and the irreversible-without-the-app consequence that justifies the destructive hint. It doesn't cover auth requirements or what the response returns, but the key behavioral risk is surfaced.

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 operation type and the highest-stakes fact (irreversibility), with no padding. Even the API endpoint mapping is a single compact clause that aids provenance.

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 7-param mutation with no output schema and minimal annotations, the description covers operation type, time format, series reuse, and the deletion gap. Missing only peripheral items like expected return shape and permission prerequisites, which are lower risk since the schema fully documents inputs.

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

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

Schema coverage is 100%, so all seven parameters (including the event_id series link and category_id default) are already documented in the schema. The description only restates the timestamp convention, adding little beyond the structured data — 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 ('create an event on the church calendar') plus the optional series-instance behavior, and prefixes with 'WRITE' to disambiguate it from the read-heavy sibling set (breeze_list_events, breeze_get_event). An agent can distinguish this from breeze_add_person/breeze_add_tag 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?

Clearly establishes the create context and adds a real usage constraint: this server cannot delete events, so mistakes must be fixed in the Breeze app. It doesn't route the agent to supporting siblings it would likely need (e.g., breeze_list_calendars for category_id, breeze_get_event to reuse event_id), so it stops short of explicit alternatives.

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 destructiveHint=true, and the description is consistent with that, additionally stating the return value ('the new profile including its id'), which matters because no output schema exists. It also discloses that profile fields can be set in the same call, though it omits permission/error behavior.

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

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

Four short sentences, front-loaded with operation type and effect; nothing is wasted except arguably the raw endpoint string. The key prerequisite and return-value facts come before the trailing API note.

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

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

For a 3-parameter mutation with full schema coverage, the description covers purpose, prerequisite, return value, and cross-referenced field semantics. It lacks any note on permissions or duplicate-handling failure behavior, which is a minor gap rather than a blocker.

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 first, last, and the nested fields structure. The description adds only a pointer that 'fields' matches breeze_update_person's shape, 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 (create a new person profile) and marks the operation type with a 'WRITE:' prefix. It is clearly distinguishable from siblings like breeze_update_person and breeze_list_people, which are named 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?

Gives a concrete prerequisite ('Check breeze_list_people first to avoid duplicates') and a cross-reference for the fields parameter shape ('same field shape as breeze_update_person'). It stops short of stating explicit when-not-to-use conditions, but the routing guidance is actionable.

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 supply destructiveHint=true with no readOnlyHint, so the description must carry most of the load. It usefully adds the 'WRITE' label and the return shape ('Returns the new tag with its id'), but says nothing about permissions, duplicate-name behavior, or whether the target folder must already exist. Consistent with annotations, no 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?

Three short clauses with the operation type front-loaded as 'WRITE:', followed immediately by what it creates and what it returns. No filler, and the endpoint reference is compact.

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 create tool with no output schema, the description covers the operation, the placement option, and the return shape. It omits error cases (duplicate names, invalid folder_id), which is a modest gap rather than a blocking one given the complete parameter schema.

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

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

Schema description coverage is 100%, so both parameters are already documented with examples and a numeric pattern for folder_id. The description only restates the top-level/folder distinction already present in the schema, adding no new semantics. 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 ('create a new tag') plus its scope ('at the top level or inside a folder'), which separates it from breeze_assign_tag and breeze_list_tags by implication. It stops short of explicitly naming those siblings, so it is clear but not fully self-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?

The phrase 'at the top level or inside a folder' implies when folder_id applies, but there is no explicit guidance on when to create a tag versus assigning an existing one (breeze_assign_tag), nor any stated prerequisites. Usage is inferable rather than spelled out.

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

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

Annotations already declare destructiveHint=true, and the description reinforces this correctly with the 'WRITE' prefix, so there is no contradiction. It goes beyond the annotation by naming the undo mechanism and disclosing the underlying Breeze endpoint (GET /api/tags/assign), though it does not describe what happens if the tag is already assigned or what the response contains.

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

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

Three tight fragments with the operation type ('WRITE') front-loaded, followed immediately by the action, the undo route, and the endpoint. No filler or redundant restatement 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 two-required-parameter mutation with fully documented params and no output schema, the description covers the action, the mutating nature, and the reversal path. Only the post-condition (e.g. duplicate-assignment behavior) is unaddressed, which is a minor 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% – both person_id and tag_id are documented as numeric Breeze ids with patterns – so the baseline of 3 applies. The description adds no format, id-resolution, or cardinality 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?

States a specific verb and resource ('add a tag to one person') and clarifies the semantic intent with a concrete example ('small group or list'). It is clearly distinguishable from the sibling breeze_add_tag (which creates a tag) and breeze_unassign_tag, so an agent can route 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?

Names the explicit reversal path ('Undo with breeze_unassign_tag'), which gives the agent a clear counterpart tool. It does not, however, state when to prefer this over alternatives like breeze_add_tag or give prerequisites (e.g. requiring the tag to already exist), so context is clear but not exhaustive.

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, so the safety profile is covered. The description adds meaningful context beyond the annotation: it is described as a cheap call and its role as a credential sanity-check, plus the return fields, which matters since there is no output schema.

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

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

Three short sentences, front-loaded with the resource and returned fields, followed by the practical use case and the endpoint. No filler.

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

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

For a zero-parameter read tool with no output schema and a readOnlyHint annotation, the description is complete: it names the returned fields and states the tool's practical purpose. Nothing needed to call it correctly is missing.

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

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

Zero parameters, so the baseline of 4 applies. Nothing in the schema needs explaining and the description correctly implies a no-argument 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 verb and resource ('Get the account summary') and enumerates exactly what is returned: name, subdomain, status, timezone, country/currency. This makes it clearly distinguishable from the list/get siblings that all target people, events, tags, or forms.

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

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

Gives explicit context for when to call it: 'A cheap way to confirm BREEZE_SUBDOMAIN and BREEZE_API_KEY are right.' This is a concrete use case (credential/setup verification), though it does not name a specific alternative tool for that job.

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=true, so the description usefully adds that results are cached by Breeze and may lag up to 15 minutes, plus that enabling schedule changes the response to an array of {id, start} only. It does not cover auth/permission needs or pagination, but the staleness and response-shape disclosures are real added value.

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

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

Three tight sentences with the core action front-loaded and no filler. The trailing 'Breeze: GET /api/events/list_event' is endpoint trivia of marginal use to an agent but costs little.

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 and does describe both response shapes; combined with annotations covering the read-only profile, an agent has enough to call it correctly. Permission requirements and pagination for large series remain unstated.

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 goes beyond the schema's terse 'Also return other instances in the same series' by explaining the consequence of the schedule flag: the response degrades to an array of {id, start} only. It adds no detail for details, eligible, schedule_limit, or schedule_direction, so it is not a full 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?

States a specific verb and resource ('Fetch one event instance') and immediately qualifies scope with the optional series expansion, which distinguishes it from the sibling breeze_list_events. An agent can tell what it returns 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?

The description makes the schedule flag's purpose explicit ('optionally with the other instances in its series'), which implies when to set it, but it never names an alternative tool (e.g. breeze_list_events) or states when not to use this one. Clear context, no explicit routing.

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

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

Beyond readOnlyHint=true, the description discloses the default payload shape: full profile fields keyed by field_id plus family members, and that the default is 'all information.' That is meaningful behavioral context an annotation cannot carry, though it says nothing about error behavior for unknown ids.

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

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

Two tight sentences front-load the core action and return shape, with the API endpoint mapping appended for reference. Slightly dense mid-sentence, but no wasted clauses.

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 the work of describing the return shape (profile fields keyed by field_id, family members), which is exactly what an agent needs. It omits not-found/error behavior, keeping it from a 5.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the terse schema text by spelling out what 'all information' actually contains (address, every field by field_id, family members) rather than just 'Defaults to true.'

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 ('Fetch one person's profile by id') and explicitly scopes to a single person, distinguishing it from the sibling breeze_list_people and breeze_get_event. An agent can pick this over the list tool 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?

Gives a concrete companion-tool instruction: 'Pair with breeze_list_profile_fields to label the field ids,' which is real workflow guidance. It lacks explicit when-not guidance (e.g., use breeze_list_people for a roster), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully frames the data as an audit log with incremental-sync semantics, but says nothing about ordering, pagination behavior beyond the schema's limit, or rate limits. With annotations carrying the read-only story, this is an adequate but not rich disclosure.

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

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

Two tight sentences front-load the core purpose and scope, followed by a short endpoint reference. Nothing is padded, though the raw 'Breeze: GET /api/account/list_log' line is marginally useful only for debugging.

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 read tool with no output schema, the description covers purpose, filters, and rationale well, but omits anything about returned record shape or result ordering. An agent can invoke it correctly; it cannot predict what it will get back.

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

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

Schema coverage is 100%, so all six parameters are already documented with patterns, ranges, and the action enum. The description restates the date-range and user filters and gives a few action examples, but adds essentially no syntax or behavioral detail beyond the schema — the baseline 3 for schema-covered params.

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

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

The description names the resource precisely (the account's audit log), constrains it to one action type, and gives concrete enum examples (person_updated, tag_assign, contribution_added). It clearly reads as distinct from siblings like breeze_get_account_summary or breeze_list_contributions, which return state rather than a change history.

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 states the intended use cases explicitly: 'what changed since…' and incremental sync, which tells an agent when this tool is the right pick. It stops short of naming an alternative or a when-not-to-use condition, so it is clear but not exhaustive.

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 readOnlyHint annotation already establishes this as a safe read, so the bar is lower. The description adds useful scope context (single event instance, and that results may be either named check-ins or an anonymous count), but says nothing about pagination, result limits, or empty-instance behavior.

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

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

One dense sentence that front-loads the core answer ('who checked in to one event instance') and tucks the returned fields into a parenthetical. Every clause carries information; the Breeze endpoint reference is cheap provenance.

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 return-value burden, and it does list the key fields returned. The three parameters are fully covered by the schema. The main gap is pagination/volume behavior for an attendance list, which is minor at this complexity level.

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 three parameters, including the person/anonymous enum. The description's mention of 'each person's details' and 'anonymous head count instead' loosely mirrors those parameters but adds no format, default, or edge-case 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?

The description gives a specific verb (list) and resource (attendance) scoped to 'one event instance', and even enumerates the returned fields (person_id, created_on, check_out), which cleanly separates it from breeze_record_attendance. It stops short of explicitly naming the sibling it must not be confused with, but the read-vs-write distinction is inferable from 'who checked in'.

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

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

Usage is implied rather than stated: the agent can infer 'call this to see attendance for a given instance_id'. The 'optionally with each person's details, or the anonymous head count instead' clause describes a parameter choice, not when to pick this tool over an alternative, and 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, so the safety profile is covered. The description adds genuinely new context: the exact returned fields (id, name, color, iCal feed address) and the underlying API endpoint, which matters because there is no output schema. Auth requirements and rate limits remain undisclosed.

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, each earning its place: what it lists, what comes back, and how the id is consumed downstream. Front-loaded with the action and resource.

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 the missing pieces: return-field shape and the id-to-category_id linkage to sibling tools. Nothing needed to invoke it correctly is absent.

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

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

Zero parameters and 100% schema coverage, so per the rubric the baseline is 4. The description correctly adds no spurious parameter detail and instead explains the semantic role of the returned 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?

States a specific verb and resource ('List the church's event calendars') and even enumerates the fields returned, which distinguishes it from sibling list tools. An agent cannot confuse it with breeze_list_events or breeze_list_tags.

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

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

Explicitly names the two downstream tools that consume its output ('The id is the category_id for breeze_list_events and breeze_add_event'), which is strong routing guidance. It stops short of stating exclusions or when this call is unnecessary.

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 the description reinforces this ('this server never adds, edits or deletes gifts') while adding non-obvious behavior: the endpoint is legacy and may fail for certain churches. It does not describe pagination or result size, which matters for a listing tool.

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

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

Three sentences, front-loaded with the core action and scope, then safety, then the operational caveat. Dense but each sentence carries distinct information; slightly packed given the filter list.

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?

Given 11 parameters and no output schema, the description covers the filtering surface, read-only guarantee, and legacy/Tithely failure mode well. It omits return shape and pagination behavior, which leaves a gap for a listing tool of this breadth.

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 11 parameters are already documented in the schema. The description enumerates the same filter categories but adds no syntax or interaction detail beyond what the schema states (e.g., that include_family only applies with person_id). Baseline 3 applies.

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

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

States a specific verb (List), resource (recorded contributions/gifts), and scope (within a date range), plus an inline definition of what counts as a contribution. An agent can distinguish it from siblings like breeze_list_funds or breeze_list_form_entries 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?

Explains the narrowing dimensions (giver/family, amount, method, fund, envelope, batch, form) and adds a meaningful when-not-to-use caveat: legacy endpoint removed from the current API reference, likely erroring for Tithely-based churches. No explicit sibling alternative is named (e.g., breeze_list_funds for fund ids), so it stops short of a 5.

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

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

The description adds real behavioral context beyond the readOnlyHint annotation: responses are cached by Breeze and may lag up to 15 minutes, which materially affects how an agent should treat freshness. It also clarifies that `id` is the instance id (not the series), a subtle but important behavioral nuance. It doesn't state pagination/ordering behavior, so not a 5.

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

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

Three dense sentences, zero filler, all front-loaded: purpose and scope first, then the critical id semantics, then the caching caveat and API path. Every sentence earns its place.

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

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

With no output schema, the description carries the return-value burden and does describe the key row fields (`id` vs `event_id`). The 15-minute cache lag covers the freshness concern. Some row fields and result ordering remain unspecified, but nothing critical to 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 start/end format, limit bounds, and category_id sourcing. The description restates the date-range and single-calendar semantics but adds no format or default detail beyond the schema, which is the expected 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 ('List event instances') and immediately scopes it by date range, default window, and optional calendar. It also disambiguates the instance-vs-series distinction that separates this tool from breeze_get_event and the attendance/volunteer tools, so an agent can tell it apart from siblings without opening either schema.

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

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

Gives a clear default behavior (current month) and the optional calendar filter, and hints at the downstream workflow by noting the id feeds attendance, volunteer and get_event tools. It stops short of explicit when-to-use/when-not guidance against a sibling like breeze_get_event, so it lands at 4 rather than 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 the description is consistent with that safety profile by naming the underlying GET endpoint. Beyond annotations it adds real context: the entry shape (id, created_on, person_id) and the conditional behavior that details=true keys responses by form field_id.

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

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

Effectively one dense sentence plus an endpoint tag, front-loaded on the resource before the conditional details behavior. Parentheticals carry useful payload rather than filler, though the sentence is packed and slightly hard to parse on first read.

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

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

With no output schema, the description correctly takes on the return-shape burden and does so for both the default and details=true modes. It omits pagination/result-limit behavior and whether entries can be empty, which are the remaining gaps for a listing 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 100%, so the baseline is 3, but the description goes further than the schema text by explaining that details=true produces responses keyed by form field_id and pointing at breeze_list_form_fields for interpreting those keys.

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 resource ('Submissions to one form') with a concrete verb and enumerates the returned identity fields (id, created_on, person_id). It also cross-references breeze_list_form_fields, so an agent can tell entries apart from fields 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?

Usage is only implied: it is a per-form listing, so form_id is mandatory, and details=true is described as the richer mode. There is no explicit when-to-use/when-not or routing to alternatives such as breeze_list_forms, and the breeze_list_form_fields mention reads as a 'see also' rather than an alternative.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds real value beyond that by disclosing the return shape (field_id, field_type, name, options) and the keying relationship to form-entry responses. For a read-only listing tool this is close to complete, missing only pagination/volume behavior.

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

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

Three short, front-loaded sentences with no filler; the returned fields are stated before the supporting rationale. The trailing endpoint string ('Breeze: GET /api/forms/list_form_fields') is mildly redundant but inexpensive.

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

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

With no output schema, the description carries the burden of describing the return and it does so by listing the field attributes and their role as keys for form entries. For a single-parameter, read-only list tool, what the agent needs to call it correctly is essentially present.

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

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

There is one parameter with 100% schema description coverage, so the schema already explains that form_id is the numeric Breeze id of the form. The description adds no numeric-format or validation detail beyond that, 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?

The description names the resource (one form's fields) and even enumerates the returned attributes (field_id, field_type, name, options), which is more than the title alone conveys. The verb 'list' is only implied, and the distinction from the nearby siblings breeze_list_forms and breeze_list_form_entries 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?

Usage is implied rather than stated: the note that 'form entry responses are keyed by these field_ids' tells the agent why field_ids matter when working with entries, which is genuine contextual guidance. However there is no explicit when-to-use, prerequisites, or routing to an alternative sibling.

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, so safety is already covered. The description adds genuine context: the default filter is active-only, archived is opt-in, and the returned payload shape (id, name, url_slug, is_archived) is enumerated — useful since no output schema exists. No permissions or pagination behavior is discussed, but for a read-only list this is solid.

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 carrying the resource, returned fields, default behavior, and the underlying API endpoint. Nothing is wasted or padded.

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 field enumeration is important and present, and the active/archived default is stated. For a one-parameter read-only list tool this is nearly complete; 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% and the single parameter is fully documented, so baseline is 3. The description restates the archived semantics and adds the default-active behavior, which the schema only implies, but contributes no new syntax or edge-case detail.

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

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

States a specific verb and resource ('List the church's online forms') and even enumerates the returned fields, so the resource is unambiguous. It does not explicitly differentiate itself from near-neighbors like breeze_list_form_entries or breeze_list_form_fields, but 'forms' vs 'entries'/'fields' is largely self-evident from the names.

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 discloses the default scope ('active ones by default, or archived ones'), which tells the agent how to get each subset via the single parameter. However, it gives no when-to-use guidance relative to other tools (e.g., when to reach for entries or fields instead), leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, but the description adds genuinely useful behavioral context beyond that: this is a legacy endpoint no longer in the current API reference, and churches running giving through Tithely may receive an error. That deprecation/failure-mode disclosure is exactly the kind of trait annotations cannot convey.

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 purpose and returned fields, then the legacy caveat, in a compact span. Including the raw 'Breeze: GET /api/funds/list' is slightly redundant for an agent but is harmless metadata that closes the description.

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

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

With no output schema, the description helpfully enumerates the returned fields and discloses the legacy error risk, which is adequate for a simple one-parameter read tool. It is complete enough to invoke correctly, missing only explicit sibling routing.

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 single parameter is already fully documented, giving a baseline of 3. The description's 'optionally with the total given to each' merely restates the schema's include_totals meaning without adding syntax or format detail.

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 and resource ('List giving funds') and even enumerates the returned fields (id, name, tax_deductible, is_default), so an agent knows exactly what surface it gets. It does not explicitly contrast with siblings like breeze_list_contributions, but the 'funds' resource is distinctive enough to differentiate.

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 explains the include_totals option ('optionally with the total given to each'), which implies when to use it, but gives no explicit when/when-not guidance against alternatives such as breeze_list_contributions. Usage 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 the description adds real behavioral context: the lighter default payload (id/first_name/last_name/photo) vs the heavier details=true payload keyed by field_id and marked "slower", plus the warning that omitting limit returns everyone and "can be large". No contradictions with the 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?

Dense and front-loaded: core behavior first, then return-shape tradeoff, then filter semantics with examples, then the API mapping. Every sentence earns its place and nothing is redundant.

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

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

Given no output schema and a nested filter object, the description adequately covers return shape, the details tradeoff, pagination, and filter key mechanics. Minor gap: it doesn't quantify the size/latency of the "large" default or pagination interaction with offset beyond the schema hint.

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 goes beyond it by explaining the filter key/value semantics with concrete examples ({"tag_contains":"y_16681"}, {"2000138015":"226-227"}) that the schema's generic string map does not convey. Details and limit/offset semantics are echoed rather than extended.

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

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

States a specific verb and resource ("List people in the church database") and immediately scopes it via optional filter/pagination, clearly distinguishing it from sibling singletons like breeze_get_person. An agent can tell what it returns and how it differs from the write 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?

Gives clear context for filtering and pagination and routes the agent to breeze_list_profile_fields to discover filter keys. It stops short of explicit when-not guidance (e.g. when to prefer breeze_get_person), so it's strong but not 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?

Annotations already declare readOnlyHint=true, so correctness is covered; the description still adds genuine context by disclosing the nested return structure (sections → fields → options) and the underlying endpoint GET /api/profile. Nothing behavioral is contradicted.

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 dense sentences with the resource declaration front-loaded and the consumer tools named afterward. Every clause carries information; no filler.

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

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

With no output schema and no parameters, the description fully carries the burden of explaining what comes back, and it does so at field granularity. Nothing an agent needs to call and consume this tool 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?

The tool takes zero parameters, so there is no parameter semantics to document; baseline is 4. The description instead spends its words on the return shape, which is the useful thing 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 the specific resource (the church's profile layout) and enumerates exactly what is returned: sections, their fields with field_id/field_type/name, and options for multiple-choice fields. This is clearly distinguishable from sibling listers like breeze_list_form_fields and breeze_list_people.

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 names three downstream uses: reading person details, building breeze_list_people filters, and writing fields via breeze_add_person/breeze_update_person. That routes the agent well, though it gives no explicit 'when not to use' or contrast against the similar list_form_fields 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 readOnlyHint annotation already establishes the safe read-only nature, so the description only needs to add context. It contributes the returned field set and the underlying endpoint (GET /api/tags/list_tags), but says nothing about pagination, result volume, or ordering for a potentially long 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?

Front-loaded with the core purpose, then the sibling routing hint, all in two tight sentences. The trailing API endpoint reference is marginally redundant with the tool name but is short and can aid cross-referencing.

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 only one optional parameter, full schema coverage, and no output schema, the description does the remaining work by naming the returned fields (id, name, created_on, folder_id). 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 coverage is 100% and the schema already defines folder_id as a numeric tag folder id, so the baseline is 3. The description adds the semantic that the parameter optionally restricts results to a single folder, which clarifies its effect beyond the schema 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 (List) and resource (tags), and helpfully disambiguates Breeze's terminology by equating tags with 'groups/lists'. It also enumerates the returned fields and the optional folder scope, though it never contrasts itself with tag-related siblings like breeze_add_tag or breeze_assign_tag.

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: use this to list tags, optionally narrowed to one folder, and it explicitly routes the agent to breeze_list_people with a filter when the goal is people inside a tag. No when-not guidance or exclusions are given, but the alternative pointer is genuinely useful.

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, so the safety profile is covered. With no output schema, the description does real work by enumerating the returned fields (person_id, response, comment, rsvped_on, role_ids), compensating for the missing return contract. It omits pagination, ordering, and empty-result behavior, so it is not fully transparent.

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 scope constraint and returned fields front-loaded and no filler. The trailing 'Breeze: GET /api/volunteers/list' line is minor redundancy given the breeze_ prefix convention across all siblings, but it is short and harmless.

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

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

For a single-parameter read with no output schema, the description supplies both the required scoping (one event instance) and the field list, which is most of what an agent needs. Remaining gaps – pagination/limits, whether the instance must belong to a specific event, and empty-result semantics – are minor for a tool this simple.

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 one parameter with 100% schema description coverage ('Numeric Breeze id of the event instance'), which already fully documents format and meaning. The description's 'one event instance' phrasing is consistent but 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?

Names a specific resource (volunteers) and narrows scope to 'one event instance', so an agent can distinguish this filtered list from the account-wide list siblings. The verb is only implicit in the name/title rather than stated, and no sibling (e.g., breeze_schedule_volunteer or breeze_get_event) is contrasted.

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

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

The phrase 'scheduled for one event instance' implicitly tells the agent this is a per-instance read and that an instance_id is required. However, there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as breeze_schedule_volunteer for writes.

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 destructiveHint=true; the description adds a genuinely non-obvious behavioral rule — checking out someone who was never checked in creates a record with matching in/out times — plus the default direction. It still doesn't say what happens on a duplicate check-in or what the resulting record contains, so it is not exhaustive.

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

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

Two compact sentences, front-loaded with the WRITE marker and the core action before the edge case; the trailing Breeze endpoint note is short and useful. No filler.

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

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

For a 3-parameter write tool with no output schema and only a destructiveHint annotation, the description covers action, scope, default, and the main edge case. It stops short of documenting permissions, duplicate handling, or the response shape, but nothing critical to invoking it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the enum by explaining that 'out' records when the person left and the edge-case semantics of out-without-in. person_id/instance_id get no extra narrative, which is fine since the schema already constrains them with patterns.

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 ('record attendance for one person at one event instance') plus the two concrete operations it performs (check in / check out). The 'WRITE:' prefix immediately separates it from the sibling read tool breeze_list_attendance without needing to open 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?

Usage is only implied: the 'WRITE:' marker and 'check in (default)' phrasing signal this is the mutation counterpart to breeze_list_attendance, but the read alternative is never named and no when-to-use condition is given. Adequate but leaves routing 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?

It leads with 'WRITE' and discloses the underlying Breeze endpoint (GET /api/volunteers/add), which usefully flags the unusual read-verb-writes-data quirk and is consistent with destructiveHint=true. However, it does not say what happens on a duplicate assignment, whether existing volunteer assignments are replaced, or what error conditions look like.

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

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

Two tight sentences with the operation type front-loaded and the API mapping second; no filler or restatement 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 two-parameter mutation with no output schema and only a destructiveHint annotation, the description covers the write intent and endpoint but omits idempotency/duplicate behavior and error handling, leaving meaningful gaps for an agent deciding whether calling it is safe.

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 parameters are documented in the schema as numeric Breeze ids, so the schema already carries the meaning. The description reinforces the cardinality ('one person', 'one event instance') but adds no id format or sourcing detail beyond what the schema 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?

States a specific verb (schedule) plus resource and cardinality (one person as a volunteer for one event instance), which is precise enough to distinguish it from the list_volunteers and add_person siblings. It stops short of explicitly naming those siblings as non-overlapping alternatives.

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

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

The description says what the tool does but never says when to reach for it versus breeze_list_volunteers or breeze_add_person, nor what preconditions exist (e.g., the person and instance must already exist). No exclusions or alternatives are offered.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds the key behavioral insight that this is a WRITE that removes only the association, leaving both the person and tag intact, which goes beyond what destructiveHint alone conveys. It does not mention auth, idempotency, or failure modes.

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, no filler. The WRITE marker, the effect, the sibling alternative, and the endpoint are all front-loaded in a compact form.

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 mutation with no output schema, the description covers the essential effect and the alternative tool. It omits auth/permission requirements and what happens on a non-existent or unassigned id, which would be expected for full completeness.

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 both person_id and tag_id are already documented in the schema. The description adds only that a single person and a single tag are affected, consistent with the schema's required single ids, but no format or id-source detail beyond what the schema provides.

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 (remove) and resource (a tag from one person), and clarifies that the person and tag both remain, which distinguishes the effect from deletion tools. The endpoint reference and named sibling (breeze_assign_tag) further disambiguate from siblings like breeze_add_tag.

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 inverse operation (breeze_assign_tag) as the way to re-assign, giving an explicit alternative. It sets clear context for when to use it, though it doesn't state prerequisites such as required permissions or whether the tag must already be assigned.

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 destructiveHint=true, and the description reinforces this by stating the previous values are overwritten and that only passed fields change (partial-update semantics). It also discloses the backing endpoint (GET /api/people/update) and a restoration workflow, though it omits auth requirements and rate limits.

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

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

Three dense sentences, front-loaded with the operation type and resource. Every clause carries information: scope, update semantics, restoration advice, and id sourcing. No filler.

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

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

For a mutation tool with no output schema, it covers scope, partial-update behavior, prerequisites, and recovery. The notable gap is the absence of any statement about what a successful update returns, which the missing output schema leaves undocumented.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds sourcing guidance beyond the schema — it states that both field_id AND option ids come from breeze_list_profile_fields (the schema documents option_id usage but not where to obtain it). No format syntax is added for the nested details object, which the schema already covers.

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?

Starts with an explicit 'WRITE: set profile fields on an existing person' and enumerates the field domains (email, phone, address, dates, options, family role, custom fields). This clearly separates it from breeze_add_person and breeze_get_person in the sibling list.

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 routes the agent to the right prerequisites: read with breeze_get_person first if values may need restoring, and fetch field_id/option ids from breeze_list_profile_fields. It gives clear context but states no explicit when-not condition.

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