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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the write/safety profile is largely covered. The description adds genuinely non-obvious behavioral detail about timezone handling ('no offset means church time') and defaulting rules, but says nothing about what happens on overlapping/duplicate blockouts, whether the blockout is visible to others, or error conditions.

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 one-line purpose, then a dense but waste-free parameter block. Every sentence earns its place, though the telegraphic clause stacking ('repeat with every=N repeats every N periods; monthly_by picks...') is harder to parse than it needs to be.

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 tool with no output schema and zero schema documentation, the description covers formats well but is silent on the return/confirmation, error behavior, whether the new blockout replaces or coexists with existing ones, and the `reason` field. Adequate but with clear gaps.

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

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

With 0% schema description coverage the description must carry parameter meaning and it mostly does: start/end formats (date vs ISO datetime), end-required-for-datetimes, offset-less = church time, every=N repetition, monthly_by day_of_month vs Nth week, repeat_until as a date. The `reason` parameter is never mentioned, leaving one of seven parameters undocumented in both schema and description.

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 ('Add') plus resource ('blockout') with the operational effect stated ('so you aren't scheduled'). It is trivially distinguishable from remove_blockout, list_blockouts and skip_blockout_date by name, but the description never names or contrasts those siblings 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?

The phrase 'so you aren't scheduled' implies the use case (marking personal unavailability), which is enough context to pick this over my_schedule. However there is no guidance on when to prefer skip_blockout_date vs remove_blockout, no mention of prerequisites, permissions, or conflict behavior.

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 this as a read-only, open-world lookup. The description adds useful behavioral context beyond the annotations: the scope is limited to the next 10 schedule entries, and email or phone fields may be null when Planning Center hides a person's details due to permissions.

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

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

The purpose is front-loaded in the first sentence, and the second sentence adds scope and permission-based null behavior without redundancy. Every sentence earns its place and the definition is appropriately short for a one-parameter lookup 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 simple read-only lookup with no output schema, the description is complete enough: it names the returned fields, states the search scope, and explains when those fields may be null. An agent has what it needs to call the 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?

With 0% schema description coverage, the description must carry parameter meaning, and it does by specifying that the single name parameter matches on any part of a person's name. It does not, however, clarify case sensitivity, exact-match fallback, or handling of ambiguous partial names.

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 the specific resource returned (email and phone) and the search method (any part of the person's name). It is clear enough to distinguish this from a generic directory tool, but it does not explicitly contrast itself with close siblings such as team_contacts or my_schedule.

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

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

The description implies the context of use by specifying people on upcoming plans and the next 10 schedule entries. It does not state when to choose this tool over alternatives like team_contacts, nor does it offer exclusions or prerequisites.

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 non-read-only, non-destructive, open-world, so the write-to-disk nature is expected; the description adds real context beyond that: files land in a configured download folder and already-current files are skipped (idempotency). It omits any auth/permission or volume/rate context.

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; the filter semantics follow, 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?

No output schema and no annotation detail on results, but the description covers destination and skip behavior, which is what an agent needs to reason about side effects. The unexplained required parameters (plan_id, service_type_id) are the remaining 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 0%, so the description must compensate. It does explain attachment_ids (with their source tool) and file_types (with an example) plus the unfiltered default, but the two REQUIRED parameters, plan_id and service_type_id, receive no explanation at all.

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

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

States a specific verb (Download) and resource (attachments) scoped to 'one of your plans', with the destination ('configured download folder') named. It also distinguishes itself from list_attachments by pointing there as the source of attachment_ids.

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 two operating modes clearly: filtered via attachment_ids/file_types, or everything when neither is supplied. It routes to list_attachments for obtaining IDs, but gives no explicit when-not-to-use guidance (e.g. volume, rate, or re-run caveats).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds the nature of the returned content (attachment metadata grouped by song), but says nothing about scope, refresh/recency, or whether this returns only metadata rather than file contents.

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

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

A single compact sentence with the resource front-loaded and the content examples in parentheses; nothing is wasted. It is arguably over-terse for a two-required-parameter tool, but there is 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 annotations describing scope, the description should carry more: it never explains how the two required IDs relate, what identifying fields each attachment carries, or how this differs from download_attachments. For a required-two-parameter listing tool it is under-specified.

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 0% for both required parameters, and the description does not mention either one. plan_id is self-evident from the prose ('one of your plans'), but service_type_id is entirely opaque and undocumented in both the schema and the description.

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 clearly (files attached to a plan) and even enumerates content types (charts, lead sheets, audio), so an agent knows what comes back. However it is a noun phrase with no explicit verb, and it does not differentiate itself from the adjacent sibling download_attachments (fetch metadata vs retrieve the file bytes).

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 statement of prerequisites, and no mention of the alternative download_attachments. The agent gets no instruction about when this list is the right call versus downloading, or how to obtain the required plan_id and service_type_id.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral detail — that returned times are in the church's time zone — but says nothing about ordering, whether past blockouts are excluded by default, or what the result looks 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?

A single tight sentence with no filler and the time-zone caveat placed up front. It is concise, though the brevity comes at the cost of under-specification rather than being a deliberate structural choice.

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 simple zero-required-parameter read tool with no output schema, a short description is defensible, and the time-zone note is valuable. However, the wholly undocumented 'include_past' parameter leaves a real gap an agent would need to close elsewhere.

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 0% for the single parameter 'include_past', and the description never mentions it. An agent cannot learn from the description that setting include_past=true is how past blockouts are surfaced, so the parameter's meaning must be guessed.

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 ('blockout dates') and implies a read via 'Your', but supplies no verb of its own; the agent must rely on the tool name 'list_blockouts'. It also does not distinguish itself from siblings add_blockout, remove_blockout, or skip_blockout_date.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives among the several blockout-related siblings. The agent is left to infer usage context entirely.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description contributes real extra context: times are church-local with a returned time_zone, and times is null when Planning Center hides the plan. These nullability and timezone semantics are exactly the kind of behavior an agent cannot infer from 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?

Front-loads the user-relevant outcome ("When you're next serving") before the field list, and every clause carries information. Slightly dense, semicolon-joined phrasing but no filler sentences.

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

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

With no output schema, the description takes on the return-value burden and discharges it well (fields, timezone, null case, IDs for follow-on tools). The only material gap is the undocumented limit parameter, which matters for a list-style 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 single parameter (limit, default 10) has 0% schema description coverage and is never mentioned in the description, so its meaning, maximum, or pagination role is undocumented anywhere. The description compensates richly on the return side but leaves the only input unexplained.

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 concretely states what the tool returns — the user's next serving assignment with date, service/rehearsal times, team, position and status. It never names itself against the sibling tools it sits beside (plan_team, service_order, etc.), so the differentiation is only implicit via the returned IDs.

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 "When you're next serving" and by the note that service_type_id/plan_id are returned "for plan_team, service_order and attachments," which hints at a chaining workflow. There is no explicit when-to-use or when-not-to-use guidance, and no statement of an alternative source for schedule data.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds that results are grouped by team and carry position and status, which is useful since no output schema exists. It says nothing about permissions, whether the plan must be active/published, or the openWorldHint implication that data may come from external systems.

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 short sentence with the salient grouping and field detail front-loaded; no filler. It is a fragment rather than a complete sentence, but nothing is wasted.

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

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

With no output schema and 0% parameter coverage, the description must do the heavy lifting, and it only partially does: the return shape is sketched, but both required parameters are undocumented and there is no usage context. An agent could guess plan_id but has no basis for supplying service_type_id.

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 0% and both parameters are required, so the description carries the full burden – yet it never explains what plan_id or service_type_id are, or how the latter scopes the result. 'One of your plans' only loosely gestures at plan_id and leaves service_type_id completely unexplained.

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 and scope – the team roster for a given plan, including position and status – which is enough to distinguish it from list-style siblings like team_contacts or my_schedule. It is written as a noun phrase describing the return rather than an action verb, and it never names or contrasts with a sibling tool.

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

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

There is no when-to-use guidance and no mention of alternatives such as my_schedule or team_contacts, which occupy adjacent roster/schedule territory. 'One of your plans' implies the caller must already know a plan id, but the condition for choosing this tool over siblings is left entirely 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds the critical scope-of-destruction detail that a repeating blockout deletes the WHOLE series, which is not recoverable from the annotations alone. It stops short of stating ownership/permission requirements or failure 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?

Two sentences, zero waste, with the destructive scope stated first and the alternative routing second. Nothing to trim.

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-param destructive tool with no output schema, annotations plus the series-deletion warning cover what an agent needs. Minor gaps remain around ownership/permissions and behavior on an invalid or already-deleted ID.

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

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

Only one parameter exists and schema description coverage is 0%; the description adds no syntax or provenance for blockout_id (e.g., that it comes from list_blockouts). The lone ID is self-describing in name, so this is minimally adequate rather than broken.

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 (delete) and resource (one of your blockouts), and explicitly distinguishes the whole-series case from the single-date case handled by skip_blockout_date. An agent can pick this tool without opening any schema.

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

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

Gives an explicit routing rule: for a repeating blockout use skip_blockout_date to drop a single date instead. The alternative and the condition that selects it are both 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 already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds useful return-content context (songs, keys, arrangements, lengths), but does not explain permissions, errors, or pagination.

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

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

The description is a single, compact sentence with no filler. Its weakness is under-specification rather than verbosity, but the phrasing is front-loaded and efficient.

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

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

For a read-only tool with two required parameters, 0% schema description coverage, and no output schema, the description does not do enough. It gives a rough sense of returned content but omits parameter meaning, usage context, and call prerequisites.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It implies plan_id via 'one of your plans' but does not explain service_type_id or the required relationship between the two parameters. Service_type_id is completely undocumented.

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 identifies the resource domain ('order of service for one of your plans: songs, keys, arrangements and lengths'), but it is a noun phrase with no explicit verb. An agent can infer it retrieves service order data, especially given readOnlyHint, but the action is not stated outright.

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

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

There is no indication of when to use this tool versus alternatives, what prerequisites exist, or what conditions apply. The nearby sibling tools are largely unrelated, so the gap is less harmful, but the description offers no usage 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 declare destructiveHint=true and readOnlyHint=false, and the description adds genuinely new context beyond them: the action cannot be undone through the API and would require the Planning Center UI or deleting the series. This is a critical warning that materially affects invocation decisions.

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

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

Two short sentences, front-loaded with the action and followed by the irreversibility warning. No filler; 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?

For a two-parameter mutation tool with no output schema, the description covers the key risk (irreversibility) and the semantic result. The only notable gap is date/ID format guidance, which is minor given the tool'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 description coverage is 0% and the description only implicitly conveys that blockout_id identifies the series while date identifies the single skipped occurrence. It adds some relational meaning but no format details (e.g., date format) that an agent would need to construct a valid 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?

The description states a specific action (make you available on one date of a repeating blockout) and clarifies the scope (keeping the rest of the series). This clearly distinguishes it from siblings like remove_blockout or add_blockout. It is not quite a crisp verb+resource phrasing but 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?

The phrase 'keeping the rest of the series' implies the use case versus remove_blockout, but there is no explicit when-to-use or when-not-to-use guidance. The agent must infer the alternative from the sibling names alone.

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

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

The description discloses a genuinely non-obvious behavioral trait: emails or phones come back null when Planning Center hides a person's details, i.e. partial results are expected. That adds real value beyond readOnlyHint/openWorldHint, though it says nothing about auth requirements or pagination.

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

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

Two short sentences, front-loaded with the return payload followed by the null caveat. Slightly awkward phrasing ('emails or phones is null') but 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?

For a read-only tool with no output schema, the description does convey what comes back and the null case. However, with two required, undocumented parameters, an agent still lacks enough to construct a correct call.

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?

Both parameters (plan_id, service_type_id) have 0% schema description coverage and no enum values, and the description says only 'one of your plans' without explaining what either id refers to or how to obtain them. The description fails to compensate for the coverage gap.

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 ('email addresses and phone numbers for the people on one of your plans') clearly enough that an agent knows this retrieves contact data for a plan. It does not distinguish itself from the sibling contact_info, so nothing tells the agent why to pick 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?

There is no statement of when to use this versus contact_info or plan_team, no prerequisites beyond the implied required ids, and no exclusions. Usage can only be inferred from the noun phrase.

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