breeze-chms

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

Annotations only carry destructiveHint=true, so the description must supply the rest — and it does: the 'WRITE' prefix, the timestamp unit convention, and the strong constraint that the server cannot delete events, meaning a mistaken creation must be cleaned up in the Breeze app. It stops short of stating auth/permission requirements. Minor tension with destructiveHint given the create-only, non-deleting nature, but not a 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 sentences, front-loaded with the operation type and the resource in the first clause. Every sentence carries distinct information (what it does, the series variant, the irreversible-mistake caveat).

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-parameter mutation with no output schema, the description covers purpose, the series option, time encoding, and the important irreversibility constraint. It lacks guidance on required permissions or which calendar defaults apply, which leaves a small 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 coverage is 100%, so the baseline is 3. The description's timestamp-unit note duplicates the schema descriptions, and 'instance of an existing series' loosely maps to event_id, but it adds no format, defaulting, or constraint detail beyond structured fields.

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?

Opens with 'WRITE: create an event on the church calendar' — specific verb plus resource — and adds the series-instance variant. This clearly separates it from siblings like breeze_add_person, breeze_add_tag, and the read-side breeze_list_events/breeze_get_event.

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

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

Explains the optional series-instance path ('optionally as another instance of an existing series'), which tells the agent how this differs from a standalone event creation. It also flags an operational rule (no delete on this server), but does not explicitly name alternative tools for correcting mistakes or check-before-create workflows.

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, so the description carries most of the burden and does well: it declares the write nature, that fields can be set in the same call, and that the new profile including its id is returned. It stops short of stating auth requirements or whether a partial failure rolls back the create.

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: the operation type, required inputs, optional behavior, precondition, and return value each get roughly one clause. The trailing 'Breeze: GET /api/people/add' is minor implementation trivia, and a 'GET' endpoint for a write is slightly odd, but it costs no real space.

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?

Covers the essentials for a create tool: inputs, optional field-setting, a duplicate-avoidance precondition, and the return shape (profile with id), with no output schema to compensate for. Missing notes on permissions/failure behavior keep it from being fully complete.

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

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

Schema coverage is already 100%, so the baseline is 3; the description exceeds that by pointing at breeze_update_person as the field-shape reference, which is genuine meaning not present in the schema. It adds nothing about the required first/last params, but those are self-explanatory.

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?

Opens with an explicit operation marker ('WRITE: create a new person profile') naming the verb and resource, and enumerates the required fields (first/last) plus optional profile fields. An agent can immediately distinguish it from breeze_update_person and the other breeze_add_* 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 a concrete precondition: 'Check breeze_list_people first to avoid duplicates,' which names the sibling tool to consult before calling. It also cross-references breeze_update_person for field shape, but does not state when *not* to use this tool (e.g. if the person already exists) beyond the duplicate warning.

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, so the description usefully adds that this is a write, that it returns the new tag with its id, and even the underlying endpoint (GET /api/tags/add_tag). The 'WRITE:' prefix aligns with the mutation hint rather than contradicting it. It stops short of noting whether duplicate names are rejected or what happens on failure.

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 operation type ('WRITE:') front-loaded. Every clause carries information an agent needs: the action, the placement options, the return value, and the endpoint.

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 write tool with no output schema, the description covers the essentials by disclosing the return payload ('the new tag with its id'). Remaining gaps are behavioral edge cases (duplicate names, error handling) rather than anything blocking correct invocation.

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

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

Schema coverage is 100%, with both name and folder_id fully documented including the top-level default, so the schema carries the semantics. The description's 'at the top level or inside a folder' merely restates the folder_id default and adds no format or constraint 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+resource ('create a new tag') and adds scope ('at the top level or inside a folder'), so the action is unambiguous. It does not explicitly differentiate from the nearby sibling breeze_assign_tag, which handles attaching existing tags, leaving a small risk of confusion for an agent scanning the 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?

There is no when-to-use guidance, no prerequisite stating that a tag must not already exist, and no pointer to breeze_assign_tag for assigning an existing tag versus creating a new one. Usage must be inferred entirely from the verb.

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 destructiveHint annotation already flags mutation, and the description adds real context beyond it: the 'WRITE:' prefix, the single-person scope, and the exact undo tool. Minor oddity: it cites 'GET /api/tags/assign' as the underlying endpoint, which reads as a non-destructive verb and sits slightly at odds with destructiveHint=true, though this is an implementation detail rather than a semantic 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, zero filler, and the write classification and scope are front-loaded before the undo hint. Every sentence 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 mutation with no output schema, the description covers the essentials: what it writes, the scope, and how to reverse it. It omits idempotency behavior (what happens if the tag is already assigned) and whether prior tags are affected, 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 description coverage is 100%, and both person_id and tag_id are documented there as numeric Breeze ids with digit-only patterns. The description adds no format, source, or lookup guidance beyond the schema, so baseline 3 applies.

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

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

The description states a specific verb and resource ('add a tag to one person') and pins the cardinality to a single person, which distinguishes it from any bulk-assignment behavior. It also names a sibling, breeze_unassign_tag, making the pair unambiguous 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?

It explicitly routes the agent to breeze_unassign_tag for reversing the operation, which is genuine when-to-use-this-instead guidance. It stops short of saying when this is preferable to other flows (e.g. mass tagging or adding a person to a group via a person-update path), so it is clear context without full alternative coverage.

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=true already establishes a safe read. The description adds useful context beyond the annotation: the call is 'cheap' (an implicit cost/rate consideration) and serves as a credential sanity check, which is a genuine behavioral trait an agent wouldn't infer from the annotations alone.

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 plus an endpoint reference, with the returned-resource identity front-loaded. Every clause earns its place; nothing is repeated from the title 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?

There is no output schema, and the description compensates by naming the fields returned, so an agent knows what to expect. The only minor gap is that it does not describe the response's shape or nesting, but for a zero-argument account lookup this is close to complete.

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

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

The tool takes zero parameters, so schema semantics are a non-issue and the baseline is 4. The description correctly adds no parameter discussion because none exists.

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

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

States a specific verb+resource (get the account summary for the key's church) and enumerates the returned fields: name, subdomain, status, timezone, country/currency. This clearly separates it from every sibling, which all deal with people, events, tags, forms or funds rather than the account itself.

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 use case: 'A cheap way to confirm BREEZE_SUBDOMAIN and BREEZE_API_KEY are right.' That tells the agent when to reach for it, though it stops short of naming an alternative tool or stating when not to call it (there isn't really a competing sibling 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?

Annotations already cover safety (readOnlyHint=true), so the description earns credit for adding real behavioral context: the response is cached by Breeze and may lag up to 15 minutes, and enabling 'schedule' silently changes the payload to an array of {id, start} only. It stops short of describing pagination or error conditions for an invalid instance_id.

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

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

Two compact sentences plus the underlying API endpoint; the core fetch behavior is front-loaded and the conditional series behavior follows. 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, the description usefully discloses caching staleness and the alternate response shape. It could go slightly further on what details/eligible add to the output, but for a single-instance read tool it is largely 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?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning the schema does not: it clarifies that the response shape degrades to {id, start} only when series instances are requested, which agents need to know before setting schedule. The interactions among schedule, schedule_limit, and schedule_direction remain implied rather than spelled out.

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 verb and resource ('Fetch one event instance') plus the optional series-expansion behavior, which clearly separates it from the sibling list tool breeze_list_events. An agent knows exactly what this 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?

Usage is implied: fetch a single instance by id, and the 'schedule' flag is explained in terms of effect. However, there is no explicit when-to-use guidance versus breeze_list_events, nor any stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral context beyond that: the response includes family members and, by default, every profile field keyed by field_id, which the agent needs to interpret results.

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 that front-load the operation and its return contents, with no filler. The trailing REST endpoint note is mildly redundant but harmless and short.

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

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

With no output schema, the description carries the burden of explaining return values and does so adequately: address, all profile fields keyed by field_id, and family members. A note on failure behavior for a missing id is the only notable omission.

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 reinforces that all profile fields are returned by default, which clarifies the details=true default, and explains the field_id keying convention. It adds meaning beyond the schema's terse parameter descriptions.

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 (fetch) and resource (one person's profile by id) and enumerates the returned contents: address, all profile fields keyed by field_id, and family members. This clearly distinguishes it from the sibling breeze_list_people, which lists many 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?

Gives clear context for correct use by telling the agent to pair the call with breeze_list_profile_fields to resolve field ids, and implies the single-person scope. It does not explicitly state when NOT to use it (e.g., vs list_people), so it stops short of the 5 tier.

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. The description adds real behavioral context beyond the schema: only one action type per invocation, the underlying Breeze endpoint, and that details are free-form/non-standardized. It doesn't discuss pagination or result ordering, keeping 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?

Three tight sentences: what it returns, how to narrow it, and what it's useful for, then the endpoint. No padding and the resource is front-loaded.

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

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

Covers the action-scoped read model, filters, and the required-action constraint for a six-parameter tool with full schema coverage. With no output schema, it could have said a bit more about what each log row contains, which is the only 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 the baseline is 3; the description lifts it slightly by framing start/end and user_id as optional narrowing filters and giving illustrative action values. It doesn't add format or semantics the schema lacks, so it stays modest.

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 ('The account's audit log'), plus the key scoping constraint that exactly one action type is returned per call. An agent can tell this is a read of audit history, not a domain listing. No sibling overlaps, so explicit differentiation isn't required, but it stops short of naming a distinct alternative.

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?

'Good for "what changed since…" and incremental sync' gives concrete usage context that maps to how an agent would pick this tool. It stops short of when-not guidance (e.g. that you cannot fetch all action types in one call, or that full-account summaries belong elsewhere).

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. The description adds the endpoint (/api/events/attendance/list) and the shape of returned fields, which is useful, but says nothing about pagination, result caps, or ordering for what could be a large 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?

A single dense sentence that front-loads the core purpose and appends the mode alternatives plus the raw endpoint. Nothing is wasted, though the parenthetical field list makes it slightly harder to parse at a glance.

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 what comes back (person_id, created_on, check_out, or a head count), and the readOnly annotation covers the safety profile. Only pagination/limit behavior for potentially large attendance lists is left 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 each of the three parameters is already documented, including the person/anonymous enum. The description reinforces that details and anonymous are optional variants but adds no syntax or format information beyond the schema, warranting the baseline 3.

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 resource (attendance for one event instance) and enumerates the returned fields (person_id, created_on, check_out) or the anonymous head count alternative. It clearly distinguishes a read of attendance from the write-side sibling breeze_record_attendance, but never names that sibling 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?

It implies when to use the tool (to see who checked in to a given instance) and flags the two modes of the type parameter, but gives no explicit when-not guidance or reference to alternatives like record_attendance or get_event. Usage is inferable rather than stated.

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

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

readOnlyHint=true already establishes the safe-read profile, and the description adds real context on top: what fields come back (id, name, color, iCal feed) and that the id is a foreign key for other tools. It does not discuss result size or ordering, but for a small enumeration this is good.

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

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

Two tight sentences, front-loaded with the resource and immediately followed by the high-value cross-tool id note. The trailing raw endpoint string (Breeze: GET /api/events/calendars/list) is mildly redundant for an agent but does not bloat the definition.

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 describing the returned fields falls to the description, and it does so. Combined with the annotations and the cross-tool key explanation, an agent has everything needed to call and use this 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. No misuse risk from parameters.

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

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

States a specific verb (list) and resource (church event calendars) and even enumerates the returned fields. It is clearly distinguishable from siblings like breeze_list_events and 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?

The description explains that the returned id is the category_id consumed by breeze_list_events and breeze_add_event, which effectively tells the agent when this call is a prerequisite. It gives no explicit exclusions or 'do not use when' guidance, 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 'Read-only: never adds, edits or deletes gifts' line is somewhat redundant. However, the disclosure that this is a legacy endpoint, absent from the current API reference, and may error for Tithely-run churches is genuinely useful behavioral context an agent cannot get from structured fields.

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 purpose before the read-only note and the endpoint caveat. Each sentence carries information, though the read-only clause partly duplicates the annotation.

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 an 11-parameter read tool with full schema coverage and readOnlyHint annotation, the description covers purpose, filters, and the important deprecation caveat. It does not describe pagination or return shape, but no output schema exists and the safety profile is annotated, so the omissions are minor.

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

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

Schema description coverage is 100%, so each of the 11 parameters is already documented in the schema. The description lists the filterable dimensions (giver/family, amount, method, fund, envelope, batch, form) 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 (list) and resource (recorded contributions/gifts) with clear scope (date range) and enumerates the narrowing dimensions. An agent can immediately distinguish this from siblings like breeze_list_funds or breeze_list_form_entries.

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 when to use it (contributions within a date range, optionally narrowed) and adds a practical warning about the legacy endpoint and Tithely-run churches erroring. It lacks explicit when-not guidance or a named alternative, but the legacy caveat gives real usage context.

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 carries the rest and delivers real value: it warns that responses are cached by Breeze and may lag up to 15 minutes, and exposes the underlying `GET /api/events` endpoint. What it does not cover (pagination behavior, whether the cache can be bypassed) keeps 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?

Three tightly packed sentences: scope first, then the critical id-semantics warning, then the caching caveat and endpoint. No filler, and the most decision-relevant fact (which id to pass downstream) is front-loaded after the 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 steps in and explains the two return fields that matter most (`id` = instance id, `event_id` = series) and which sibling tools consume them, plus the default date window and staleness. An agent has everything needed to call and interpret this tool 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the date-range default of the current month and the framing of `category_id` as 'one calendar'. It stops short of explaining `details` or `eligible` further than the schema already does.

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 event instances in a date range') with scope (default current month) and an optional calendar filter. It goes further by distinguishing itself from `breeze_get_event` via the instance-id vs series-id distinction, so an agent can tell the two apart 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?

Usage context is implied rather than stated: naming `get_event`, attendance and volunteer tools as consumers of the instance `id` hints at when this list tool is the right entry point, but there is no explicit 'use this when / use X instead when' guidance or exclusion. Nothing is misleading, but the agent must infer the selection rule.

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

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

Annotations declare readOnlyHint=true, so the safety profile is already covered; the description adds real value beyond that by disclosing the return shape (id, created_on, person_id) and the fact that responses are keyed by form field_id when details=true. It also names the underlying Breeze endpoint (GET /api/forms/list_form_entries). It stops short of 5 because it says nothing about pagination, ordering, or result limits.

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

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

A single dense sentence with no filler; the core behavior (list submissions for one form) is front-loaded before the details flag and the sibling reference. Slightly run-on with parenthetical nesting, but 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?

With no output schema and only two parameters, the description usefully compensates by naming the returned fields and explaining the field_id keying, plus a sibling pointer for resolving those keys. It is close to complete for a simple read tool, with pagination/limits being the main omission.

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 in the schema and the baseline is 3. The description clarifies the semantics of details=true (each entry's responses keyed by field_id) and implicitly that form_id is the numeric form identifier, but adds no format or constraint detail beyond that.

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 ('Submissions to one form') and enumerates the returned fields (id, created_on, person_id), which is more precise than the title alone. It also explicitly cross-references the sibling breeze_list_form_fields for interpreting field_id keys, so an agent can distinguish it from that sibling 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 implied by the description: use this to fetch submissions for a form, and use breeze_list_form_fields to resolve field ids. There is no explicit statement of when NOT to use it (e.g., use breeze_list_forms first to obtain a form_id), so the routing guidance stops short of a 4.

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 establish readOnlyHint=true, so safety is covered. The description adds that entry responses are keyed by field_id, which is genuinely useful behavioral context, but says nothing about volume, pagination, or error behavior for a per-form listing.

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

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

Three short sentences, front-loaded with what is returned, then the consumer-facing note about field_ids. The trailing 'Breeze: GET /api/forms/list_form_fields' is marginal but compact and does not obscure the substance.

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-only tool with no output schema, the description usefully enumerates returned attributes and explains how the results are consumed downstream. Only volume/pagination expectations remain 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% — form_id is already documented as the numeric Breeze id of the form. The description adds no syntax, format, or constraint detail beyond what the schema provides, 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+resource: lists the fields belonging to one form, and enumerates what each item contains (field_id, field_type, name, options). This distinguishes it from breeze_list_forms (forms themselves) and breeze_list_form_entries (entry data), though the differentiation is implied rather than stated.

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

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

The note that 'form entry responses are keyed by these field_ids' implies the tool's purpose (mapping entry values back to human-readable fields), which is useful contextual guidance. However, there is no explicit when-to-use vs. when-not, and no named alternative such as breeze_list_forms.

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; the description goes further by disclosing the exact fields returned and the underlying API endpoint. With no output schema present, listing the returned fields is genuinely additive context rather than repetition.

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 and tight: one sentence covering scope, fields, and the default/archived switch, plus a short endpoint note. The trailing 'Breeze: GET /api/forms/list_forms.' is implementation trivia that adds little for an agent deciding how to call the tool.

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, no-output-schema list tool, the description covers scope, defaults, and return fields, which is close to complete. The only missing piece is disambiguation from the closely named form-entry and form-field siblings.

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's own description already states 'true = list archived forms instead of active ones.' The description restates that default/override behavior but adds no syntax or interpretation 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?

Specific verb+resource ('List the church's online forms') with the returned fields named (id, name, url_slug, is_archived), so an agent knows exactly what it gets. It does not, however, distinguish itself from related siblings like breeze_list_form_entries or breeze_list_form_fields, which an agent could easily confuse for this one.

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 active-vs-archived default is stated, which implies when each mode applies, but there is no explicit guidance about when to reach for this tool versus breeze_list_form_entries or breeze_list_form_fields. Usage is inferable from the description but not spelled out.

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

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

Annotations already declare readOnlyHint=true, but the description adds real behavioral context beyond that: it is a legacy endpoint no longer in Breeze's current API reference, and churches whose giving runs through Tithely may get an error. That warning meaningfully affects whether an agent should call or fall back.

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

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

Three compact sentences, front-loaded with the resource and returned fields, then the optional-totals note, then the legacy warning and endpoint reference. Every sentence carries information, though it is slightly dense in the final sentence.

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 usefully names the returned fields, and the single parameter is fully covered by the schema. Combined with the readOnly annotation and the legacy risk note, an agent has enough to invoke this correctly; only the relationship to sibling list tools 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 description coverage is 100%, so the single parameter include_totals is already fully documented in the schema. The description's phrase 'optionally with the total given to each' mirrors that semantics without adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List giving funds') and even enumerates the fields returned (id, name, tax_deductible, is_default), so the agent knows exactly what comes back. It does not explicitly differentiate from adjacent list tools like breeze_list_contributions, which is the only gap.

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 through 'optionally with the total given to each,' which tells the agent when to set include_totals, and the legacy/Tithely error caveat is genuinely useful pre-call context. However, there is no explicit when-to-use versus sibling tools such as breeze_list_contributions, so the guidance is only partially 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?

With readOnlyHint already declaring this a safe read, the description still adds real value: it discloses the performance trade-off of details=true ('slower') and warns that omitting limit returns everyone ('can be large'). It does not discuss auth or rate limits, but the core behavioral caveats are 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?

Purpose is front-loaded and each sentence carries distinct information (filtering, output shape, filter semantics, endpoint). It is information-dense rather than padded, though the run-on filter examples make it slightly heavy to parse.

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

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

No output schema exists, so the description must carry the return-value burden, and it does: it specifies the default fields (id, first_name, last_name, photo path) and the details=true shape keyed by field_id, both of which are essential for an agent to correctly consume the result.

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: it explains that filter keys are profile field_ids or special keys and gives two concrete examples (tag_contains, Status option ranges), which the schema's generic 'additionalProperties: string' cannot convey. It also clarifies the details field's output effect.

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 qualifies scope with optional filtering vs pagination. An agent can distinguish this list-and-filter endpoint from single-entity siblings like breeze_get_person 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 clear context for when and how to use it: use filters keyed by field_id, and it routes the agent to breeze_list_profile_fields to discover those keys. It stops short of explicit when-not or alternative statements (e.g., versus breeze_list_volunteers), so it earns a 4 rather than 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?

readOnlyHint=true already declares the safety profile, so the description's job is to add context beyond that. It does so by disclosing the structure of the returned data (sections, multiple-choice options) and how the result feeds other operations, though it says nothing about caching, auth/permissions, or size.

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 resource and its structure, followed by a single routing sentence and the backing endpoint. Every clause carries information; nothing is redundant padding.

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

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

With no input parameters and no output schema, the description must carry the return-value burden itself, and it does: it enumerates the nested entities and their key fields. An agent can call this and interpret the response with no further context.

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 for the description to clarify and the baseline of 4 applies. The identifiers it lists (field_id, option_id, name) are return-value fields, not inputs, but they usefully signal the keys an agent will later pass to breeze_update_person filters.

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

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

Specific verb+resource ('List profile fields' = the church's profile layout) plus an explicit account of the return shape (sections, fields with field_id/field_type/name, options with option_id/name). This clearly distinguishes it from siblings like breeze_list_tags, 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?

It states concrete downstream uses: reading person details, building list_people filters, and writing fields via breeze_add_person / breeze_update_person, which effectively tells the agent when this tool is a prerequisite. It does not name an alternative tool that returns similar metadata or state when this call is unnecessary, 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral value beyond that: the exact returned fields, and the non-obvious convention that tag membership is queried via a 'y_<tag_id>' filter on a different tool. It does not discuss pagination or result limits.

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

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

Front-loads the purpose and returned fields, then appends the cross-tool routing hint; both sentences earn their place. The trailing 'Breeze: GET /api/tags/list_tags' is low-value filler for an agent but cheap and skimmable.

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

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

With no output schema, the description compensates by naming the return fields, and it explains the cross-tool workflow needed to get tag members. Nothing critical is missing for correct invocation; only pagination/limits are unaddressed.

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

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

Schema description coverage is 100% and the single folder_id parameter is fully documented there (including the numeric pattern). The description only restates that filtering is optional ('optionally only those in one folder'), adding no syntax or format 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 and resource ('List tags'), disambiguates the term by glossing tags as 'Breeze's groups/lists', and enumerates the returned fields (id, name, created_on, folder_id). An agent can distinguish this from sibling list tools 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 clear use condition ('optionally only those in one folder') and routes an adjacent task to a named alternative ('To list the people in a tag, call breeze_list_people with filter {tag_contains: y_<tag_id>}'). No explicit when-not-to-use guidance, but the routing 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 readOnlyHint annotation already declares this a safe read, so the description needn't cover safety. It does add value by naming the return fields (person_id, response, comment, rsvped_on, role_ids), which is useful since no output schema exists, but it says nothing about pagination, ordering, or what an empty result means.

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 fragments, front-loaded with the resource/scope and then the field list. The trailing raw endpoint reference adds little for an agent but costs nothing in length.

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 tool with readOnlyHint coverage and no output schema, the description compensates by listing return fields and stating the scope. 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% for the single instance_id parameter, and the schema documents its numeric-id format and pattern. The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States the resource (volunteers scheduled) and the scope (one event instance), which distinguishes it from event/person-listing siblings, and enumerates the fields returned. It doesn't use an explicit verb, but the intent is unambiguous.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives among siblings such as breeze_get_event or breeze_list_people. The agent must infer from the name alone that this is the volunteer-enumeration path.

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, so the description carries most of the burden — and it does, flagging 'WRITE' up front and explaining the resulting record semantics for the out direction. It omits auth/permission requirements and does not address idempotency or duplicate check-ins, which are plausible concerns for a mutation tool.

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

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

One dense, front-loaded sentence: the operation type ('WRITE') comes first, then scope, then the mode semantics. Every clause carries information; nothing is padding.

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

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

With no output schema and only a destructiveHint annotation, the description supplies the write semantics and mode behavior an agent needs to call it correctly. It lacks any note on permissions or failure modes, which would round out a mutation tool description.

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 real meaning beyond the schema by explaining that 'out' records when the person left and what happens if they were never checked in — behavior the enum description 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?

States a specific verb (record attendance), the resource (attendance for one person at one event instance), and the two modes (in/out). It is clearly distinguishable from the sibling breeze_list_attendance, which reads rather than writes.

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 establishes the default (in) and the non-default (out) plus a non-obvious edge case (checking out someone not checked in creates a record with matching in/out times). It doesn't explicitly name when to prefer this over other write tools like breeze_add_event, but the scope is narrow enough that context is clear.

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

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

Annotations supply destructiveHint=true, but the description adds no behavioral detail beyond the annotations: no statement about reversibility, whether an existing assignment is overwritten, auth requirements, or duplicate handling. It only restates that this is a write and names the upstream endpoint.

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

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

Two terse sentences with the operation type and scope front-loaded. 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?

For a 2-param mutation with 100% schema coverage and a destructiveHint annotation, the essentials are technically covered, but the destructive flag on a scheduling action is left unexplained and there is no note on side effects or failure modes.

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 required Breeze ids, so the schema fully documents inputs. The description adds nothing 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 (schedule), resource (volunteer), and scope ('one person ... one event instance'). The 'WRITE' prefix immediately separates it from read siblings like breeze_list_volunteers.

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 'WRITE' marker and 'schedule one person' imply usage context, and it implicitly contrasts with breeze_list_volunteers. However, no explicit when-to-use vs when-not guidance or alternative is named.

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 usefully narrows that scope by clarifying that both the person and the tag survive the call, so only the association is destroyed. It also discloses the backing endpoint (GET /api/tags/unassign), which is notable since a write is performed via GET. No auth or rate-limit context, so not a 5.

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

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

Three short sentences, front-loaded with a 'WRITE:' marker, each carrying distinct information: the operation, the non-destructive-to-entities clarification plus alternative, 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 two-parameter association-removal tool with full schema coverage and no output schema, everything an agent needs is present, including re-assignment guidance. Return value shape is unspecified, but that is minor given the operation's simplicity.

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 parameters (person_id, tag_id) are already documented with their numeric-id pattern. The description only implies the person/tag pairing and adds no format or constraint 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+resource ('remove a tag from one person') and explicitly distinguishes itself from the sibling breeze_assign_tag, which handles the inverse operation. An agent can route between 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?

Names the alternative tool (breeze_assign_tag) and the condition that selects it (re-assignment). It doesn't state exclusions, e.g. whether tag objects themselves can be deleted here, but the routing is clear.

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

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

destructiveHint=true is already declared, but the description goes further by explaining the partial-update semantics ('only the fields you pass change') and the destructive consequence ('previous values are overwritten') plus a recovery path. It does not mention permission or rate-limit requirements, so it is short of 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?

Front-loaded with the WRITE marker and the resource, then the overwrite caveat, then the id source. Only the trailing 'Breeze: GET /api/people/update.' line is of marginal value to an agent choosing a tool, and it reads oddly for a write endpoint.

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 what changes, what is destroyed, and where dependent ids come from, which is most of what an agent needs. It stops short of stating required permissions or whether the response confirms which fields were applied.

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 nested field structure, field_type values, details shapes, and id patterns are already documented. The description's note that field_id and option ids come from breeze_list_profile_fields is genuinely useful sourcing context but does not add syntax 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 ('set profile fields') on a specific resource ('an existing person') and enumerates the field families affected. The 'existing person' framing cleanly separates it from breeze_add_person, and the WRITE prefix makes the mutation nature unmistakable.

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 conditional: read values first with breeze_get_person if you may need to restore them. Also routes the agent to breeze_list_profile_fields for field_id and option ids, so the prerequisite chain for a successful call is fully spelled out.

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