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

Annotations already indicate mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). Description adds that it returns a new Schedule, which aligns. No contradictions, but lacks detail on side effects or parameter constraints.

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 concise sentences plus arg list, no wasted words. Front-loaded with core action. Ideal structure for quick comprehension.

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 output schema present and one parameter fully described, the tool is completely specified. Sibling list provides context for alternative tools. No gaps.

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

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

Schema provides only type and title ('Schedule Id'), while description adds 'Schedule UUID to copy', clarifying the parameter's purpose. With 0% schema coverage, the description compensates well for a single parameter.

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?

Description clearly states 'Duplicate an existing schedule' with specific verb and resource. Differentiates from siblings like create_schedule and update_schedule by suggesting a workflow: copy then update to rename.

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

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

Explicitly mentions use case: 'creating seasonal variants from an existing template' and suggests pairing with update_schedule. Lacks explicit when-not-to-use, but context is sufficient given sibling tool list.

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 states that the tool 'Persists to the Rachio backend', disclosing its write behavior. Annotations confirm readOnlyHint=false, destructiveHint=false, and idempotentHint=false, which are consistent. The description adds value by noting the persistence effect, but could further describe side effects or post-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?

The description is well-structured with a brief intro, a key usage paragraph, and a bulleted parameter list. It front-loads the purpose and critical recommendation. Minor redundancy ('Every argument has the same meaning as in preview_schedule' appears twice) slightly reduces conciseness.

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

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

Given the tool's complexity (19 parameters, 1 recommended sibling), the description provides parameter details, usage guidance, and behavioral context. The presence of an output schema relieves the need for return value documentation. Minor gaps: no mention of error conditions or authentication requirements, but still fairly complete for an agent.

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 schema description coverage at 0%, the description compensates thoroughly by listing all 19 parameters in a clear Args block with meanings, types, and defaults. It even references preview_schedule for nested structures (zones). This provides complete semantic coverage beyond the bare schema.

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

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

The description clearly states 'Create a new schedule' with a specific verb and resource. It distinguishes from sibling tools like preview_schedule, update_schedule, delete_schedule, etc., as it explicitly mentions creation and persistence.

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 strongly recommends calling preview_schedule with the same arguments before creating, providing clear usage context. It also indicates that field details are covered in preview_schedule's docstring. However, it does not explicitly state when not to use this tool (e.g., when updating or deleting is more appropriate).

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 indicate destructiveHint=true. The description adds 'cannot be undone,' reinforcing permanence, but no additional behavioral traits like associated data deletion or permission requirements are disclosed.

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?

Very short and front-loaded with key info. The Args section is redundant with the schema but adds minor clarity. No wasted 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?

For a simple destructive operation with one parameter and an output schema, the description covers the essential: what it does and the input. Missing return value details are covered by the output schema.

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

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

Schema coverage is 0%, so the description must compensate. It describes schedule_id as 'Schedule UUID to delete,' which adds basic meaning beyond the schema's title and type, but lacks format or constraints.

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 clearly states the tool permanently deletes a schedule, using a specific verb and resource. It is distinct from sibling tools like create, update, or copy, which perform different operations.

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

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

No guidance on when to use this tool versus alternatives (e.g., skipping a schedule, disabling it). No prerequisites or when-not-to-use conditions are provided.

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; description adds context on what alerts include (low flow, high current, etc.) and the one-of constraint. No contradictions.

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?

Description is concise with 4 sentences and a list, no filler. Structure is front-loaded with purpose, then parameters.

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

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

Given the tool has only 2 parameters and an output schema, the description covers purpose, constraints, parameter meanings, and example alert types. No gaps.

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

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

Schema coverage is 0%, but description provides meaningful docstrings for both parameters, specifying they are UUIDs for controller and zone respectively.

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 clearly states the tool returns unresolved alerts for a device or zone, with specific examples of alert types. It is distinct from sibling tools like get_device or get_zone.

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

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

Explicitly states that exactly one of device_id or zone_id must be supplied, providing clear usage constraint. Does not explicitly differentiate from siblings, but purpose is clear enough.

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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral context on response contents (runs with per-zone details, skips) without contradicting annotations.

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

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

Four concise sentences that front-load the core function, then provide context, response details, and parameter listing. No redundant wording.

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

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

Given annotations, input schema, and existence of output schema, the description covers all needed context: purpose, usage, parameters, and response overview.

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?

All three parameters are described: device_id as Controller UUID, start and end as ISO dates with default values. Schema coverage is 0%, so description fully compensates.

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?

Clearly states it returns scheduled runs and skip events for a device in a date range. Includes specific use cases to illustrate intent.

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?

Provides clear use cases like 'what's going to water this week?' but does not explicitly differentiate from siblings like get_schedule_runs. Still highly informative.

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 idempotentHint, so the safety profile is clear. The description adds value by explaining the combination of static and live state, and the null state condition, providing behavioral context beyond annotations.

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 concise (about 5 lines), well-structured with a main paragraph and an Args section. It is front-loaded with the core purpose and avoids unnecessary details.

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

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

Given the presence of an output schema, the description does not need to explain return values. It covers input, the scope of details (static and live state), and edge cases (null state), making it complete for a single-device retrieval 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 description explains that device_id is a 'Device UUID from list_devices,' adding meaning to the parameter beyond the schema's type and title. This is especially valuable given 0% schema description coverage.

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 explicitly states 'Get full details + live state for a single device,' clearly identifying the action (get) and resource (device). It distinguishes itself from siblings like list_devices (multiple devices) and get_zone (different resource).

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 provides context about when state is null (linked sensors, virtual weather stations), offering practical usage guidance. However, it does not explicitly mention when to use this tool versus alternatives or when not to use it.

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

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

Adds context beyond annotations: explains response includes actual_zone_runs and calendar_runs/skips, notes limitations (calendar events may be incomplete, observed telemetry is source of truth, limited to latest run per zone). No contradictions with annotations.

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?

Very concise with clear structure: one-line purpose, usage guidance, response explanation, parameter list. Every sentence adds value, no fluff.

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?

Complete for a read-only history tool with output schema. Covers return value nature, limitations, defaults, and references sibling tool. No 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?

Despite 0% schema coverage, description fully explains all three parameters: device_id as 'Controller UUID', start and end with ISO format and default values (today - 7 days for start, tomorrow for end). Compensates for schema 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?

The description clearly states the verb 'return' and resource 'watering history for a controller.' It distinguishes from sibling tool get_schedule_runs by specifying when to use that alternative for schedule-specific audit trails.

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

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

Explicitly says it's the best first tool for questions like 'what ran today?', 'when did this controller water recently?', or 'did anything skip?'. Also directs to use get_schedule_runs for schedule-specific audits.

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, openWorldHint, idempotentHint, and destructiveHint. Description adds value by detailing the return structure (schedule proto contents, locations_and_devices) without contradicting annotations.

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 concise paragraphs with no fluff. The first paragraph states the purpose and output, the second clarifies the parameter. Efficiently 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?

Given the tool's simplicity (one parameter, read-only, output schema exists), the description fully covers what an agent needs: what it does, what it returns, and where the parameter comes from.

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 has one parameter with 0% description coverage. Description fully compensates by explaining the parameter's purpose ('Schedule UUID from list_schedules'), providing complete semantics 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?

Clearly states it retrieves a single schedule and its associated locations/devices. Lists the components of the schedule (criteria, restriction criteria, etc.) and provides parameter context from list_schedules, distinguishing it from sibling tools like list_schedules and get_device.

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?

Provides parameter guidance (schedule_id from list_schedules) and implies use for specific schedule retrieval. Could be more explicit about when not to use it or alternatives like preview_schedule, but adequate for a simple read tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., so no contradiction. The description adds that it returns runs and skips within a date range, which is meaningful behavioral context beyond annotations. It does not add details on rate limits or other traits, but given the strong annotation coverage, this is adequate.

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 two sentences plus parameter list, front-loaded with purpose. The example usage is efficient and adds value without fluff. 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?

Given the tool has an output schema (so return values don't need explanation) and annotations are strong, the description covers purpose, parameters, and a use case. It is complete for a simple read-only query tool.

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

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

Schema coverage is 0%, so description fully compensates. It explains 'schedule_id' as 'Schedule UUID', and specifies 'start' and 'end' dates with ISO format and defaults ('today - 30 days' and 'today'). This adds clear meaning beyond the bare schema.

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

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

The description clearly states the tool returns 'past runs + skips for a schedule in a date range', using specific verbs and resources. It distinguishes itself from siblings like 'get_run_history' and 'get_schedule' by focusing on runs and skips for a single schedule with date filtering.

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 provides a concrete use case ('did my Summer Lawn actually water last week?') and specifies default date ranges, giving clear context for when to use. However, it doesn't explicitly mention when not to use or compare to similar siblings like 'get_run_history', so it's slightly incomplete.

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, destructiveHint, idempotentHint, and openWorldHint, so the description only needs to add context beyond that. It does so by detailing the returned fields and the tool's purpose in climate-skip logic, providing value without contradiction.

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

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

The description is well-structured with a clear first sentence summarizing the tool, a list of included fields, a usage note, and parameter documentation. It is slightly verbose but 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?

The description covers parameter semantics, output content, and a use case. Since an output schema exists, return value details are not needed. It lacks error handling or rate limit info, but for a simple weather read tool with good annotations, it is adequately complete.

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

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

Schema description coverage is 0%, so the description must fully compensate. It manually documents all three parameters: location_id (source and UUID format), start (ISO YYYY-MM-DD with default), and end (ISO YYYY-MM-DD with default). This adds significant meaning beyond the schema's type definitions.

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 ('Return') and resource ('observed + forecast weather readings for a location'), lists the included data elements (temperature, precipitation, humidity, wind, ET), and distinguishes the tool from siblings (no other weather tools). It also notes its use in 'Rachio's climate-skip logic,' adding unique context.

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 default date ranges and that location_id comes from a device's location_id field, implying when to use this tool (to get weather data for a device). It does not explicitly exclude scenarios, but with no alternative weather tools, this is sufficient.

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, idempotentHint, destructiveHint false. The description adds that it returns 'live state', indicating real-time data (consistent with openWorldHint), and details the return content (configuration and state). No contradictions or omissions.

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 extremely concise: a one-line summary, a list of returned fields, and parameter explanations. No redundant words; every sentence adds value.

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 tool with annotations covering safety and an output schema (not shown), the description adequately covers purpose, parameters, and return content. No missing critical information.

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 covers 0% of parameter descriptions. The description fully compensates by explaining zone_id as a UUID from list_zones and force_imperial's effect on unit system (imperial vs metric). This provides complete semantics.

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 clearly states the tool retrieves full zone detail and live state for a single zone, distinguishing it from sibling tools like list_zones (list all zones) or get_device (device info). The verb 'Get' and resource 'zone' are specific, and the listed fields (soil, nozzle, crop/plant, etc.) provide concrete detail.

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

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

The description implies usage context by noting zone_id comes from list_zones, guiding the agent to first list zones. It does not explicitly exclude other tools or state when not to use it, but the hint is clear enough for an AI agent.

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, idempotentHint=true, and destructiveHint=false. Description adds useful context about device types and return format, but does not contradict annotations.

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?

Well-structured: opens with purpose, then lists device types, filtering guidance, return format, and sibling reference. Every sentence adds value, no waste.

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 parameters, annotations covering safety, and output schema present, the description fully explains what the tool returns and how to use it. Complete for a list 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?

No parameters; baseline 4 applies. Description adds no param info, which is acceptable given zero 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?

Clearly states the tool lists all Rachio devices, enumerates types, and distinguishes from get_device which provides full details. Specific verb+resource with scope.

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

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

Explicitly suggests filtering by type client-side for irrigation controllers and recommends get_device for full details. Provides clear context on when to use vs alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's behavioral safety is clear. The description adds the constraint of exactly one argument, which is helpful, but does not disclose other behaviors like pagination or ordering. Given annotations, this is adequate.

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 very concise: one sentence for the main action followed by a bullet list of parameters. It is front-loaded and every sentence adds value.

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

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

Given the output schema exists, return values need not be described. The description covers all parameters and the constraint of exactly one argument. It is complete for a list tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains each parameter's purpose: 'all schedules on a controller' for device_id, 'all schedules at a property' for location_id, etc. This adds significant meaning beyond the raw schema.

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

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

The description clearly states 'List schedules matching exactly one filter' and enumerates the specific filters (device_id, location_id, zone_id, schedule_id). This provides a specific verb and resource, and the filter options distinguish it from sibling tools like get_schedule or list_devices.

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 explicitly states 'Exactly one argument must be supplied,' which is a clear usage guideline. It also explains what each filter does. However, it does not mention when not to use this tool or suggest alternatives, but the constraint is sufficient for a list tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. The description adds value by detailing the output structure: each zone summary includes zone_detail (with fields listed) and zone_state. This goes beyond annotations to inform the agent of what to expect.

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 extremely concise: one summary sentence, then a bullet-like list of return fields, then clear Args list. No extraneous words. It is front-loaded with the core purpose. 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?

The tool is relatively simple (list zones). The description covers purpose, return structure, and all parameters. Annotations provide safety/behavioral context. Output schema exists (but not shown) and the description already explains the return format. A minor gap: no mention of pagination or handling large numbers of zones, but typical controllers have few zones, so this is acceptable.

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 fully compensates. It provides clear explanations for each parameter: device_id is 'Controller UUID (must be a CONTROLLER_GEN* device)', include_extra 'Ask the server to populate extra diagnostic fields', and include_moisture 'Include per-zone moisture data.' This adds meaning beyond the parameter 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 clearly states the tool's purpose: 'List all zones configured on a controller.' It uses a specific verb (list) and resource (zones), with a clear scope (on a controller). This distinguishes it from sibling tools like get_zone (single zone) or start_zones (action) without needing explicit comparison.

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 that this tool is for obtaining an overview of all zones, but it does not explicitly state when to use it vs alternatives like get_zone. It provides a usage constraint: device_id must be a CONTROLLER_GEN* device. No comparisons or exclusion guidance is given.

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

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

Adds behavioral context: zone is paused for specified duration, auto-resumes. No contradiction with annotations (readOnlyHint=false). Could detail error conditions or multiple zone behavior, but adequate.

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?

Very concise: three short sentences for purpose, usage, and parameters. No wasted words, front-loaded with core action.

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 purpose, usage, and parameters. Output schema present so return values not needed. Could mention edge cases like zone not running, but complete enough for simple 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?

With 0% schema coverage, description fully explains both parameters: device_id is controller UUID, seconds is duration (1-3600). Adds meaning beyond 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?

Description clearly states verb (pause) and resource (currently-running zone), and distinguishes from siblings like stop_watering and resume_watering by specifying automatic resume after seconds.

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

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

Explicitly mentions when to use resume_watering for early continuation and implies that pause auto-resumes. Could also mention stop_watering as alternative for permanent stop, but guidance 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 already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that the tool returns the same schedule as create_schedule would (including a server-generated summary), and that it does not persist anything, providing useful extra behavioral 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?

The description is well-structured with a clear front-loaded purpose statement and a labeled Args section. However, it is verbose with bullet-point-style parameter descriptions; could be slightly more concise while remaining complete.

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

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

Given the high parameter count (18), 0% schema coverage, and presence of an output schema, the description covers all essential aspects: purpose, usage flow, detailed parameter semantics, and behavioral guarantees. It is fully adequate for the AI agent.

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%, but the description compensates fully with detailed explanations for each parameter, including format constraints (e.g., 'HH:MM', 'MON/TUE...', 'MM-DD') and mutual exclusivity (e.g., provide at most one of start_time or start_sun).

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 clearly states it is a 'Server-side dry-run of create_schedule' and explicitly says 'Does NOT persist anything'. This verb-driven purpose distinguishes it from the sibling create_schedule 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?

The description instructs 'Always call this first and verify the summary + zone breakdown before calling create_schedule', providing explicit when-to-use guidance and an alternative workflow.

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

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

The description adds minimal behavioral context beyond the annotations. It states it resumes a paused run, but doesn't disclose what happens if no zone is paused, side effects, or error conditions. Annotations already indicate it's not read-only.

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 very concise with two short sentences, but it may be too minimal. It effectively communicates the core purpose without unnecessary 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 tool that resumes a paused operation, the description omits important context such as prerequisites (must have a paused run), possible outcomes, or error scenarios. The presence of an output schema may mitigate some return value details, but the description remains incomplete.

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 description adds specificity to the device_id parameter by labeling it as 'Controller UUID', which is more informative than the schema's 'Device Id'. However, it does not explain how to obtain this UUID or any constraints. With 0% schema coverage, more detail would be beneficial.

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 clearly states the action (resume) and the resource (paused zone run), making it distinguishable from siblings like pause_watering or start_zones. However, it does not explicitly differentiate from alternatives.

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

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

No guidance is provided on when to use this tool versus alternatives like start_zones or when a pause is required. The description simply states what it does, not when it should be invoked.

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 indicate mutability and non-idempotency. The description adds that it returns a list of device_ids, but does not disclose other behavioral details like prerequisites, conflicts, or interactions with ongoing watering. It adds some value beyond annotations.

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 very concise: three sentences covering purpose, return value, and parameter. It is front-loaded with the action, and every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description covers the essential aspects. It could mention potential effects or prerequisites, but overall it is sufficiently complete for an agent to use 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?

The schema description coverage is 0%, but the description explains 'schedule_id: Schedule UUID to run', which adds basic meaning beyond the schema title. However, it does not elaborate on format or constraints, so it meets a baseline level.

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 clearly states the action 'Start an immediate run of the schedule right now' with a specific verb and resource. It distinguishes from sibling tools like preview_schedule and schedule management tools, making its unique purpose evident.

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

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

The description implies usage for triggering immediate execution but does not explicitly state when to use or avoid using this tool, nor compare it to alternatives such as preview_schedule or skip_schedule. Minimal guidance is provided.

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 indicate idempotent and non-destructive write operation. The description adds behavioral context: the device will not run schedules until the expiration time, and shows how to cancel. This is useful beyond annotations.

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 concise: a single sentence for the main action, followed by a clear explanation and structured 'Args:' section. Every sentence adds value, no fluff.

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

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

Given the tool's simplicity and the presence of an output schema (not shown), the description covers key aspects: purpose, parameters, and cancellation. It lacks mention of error handling or prerequisites, but is sufficient for an agent to use 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 fully compensates by explaining device_id as 'Controller UUID' and expiration as 'ISO-8601 datetime', including an example and cancellation value. This adds significant meaning beyond the bare schema.

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

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

The description clearly states the verb 'Set' and resource 'rain-delay expiration for the device', and explains its effect (prevents schedules from running). It distinguishes from siblings like skip_schedule or pause_watering by focusing on a specific rain delay mechanism.

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 provides usage guidance (how to set and cancel a delay via a specific datetime) but does not explicitly tell when to use this tool versus alternatives. No exclusions or when-not instructions are given.

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

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

The description adds the condition 'Does nothing if no schedule is running,' which is a useful behavioral trait beyond the annotations (readOnlyHint=false, destructiveHint=false). However, it does not elaborate on other behaviors like idempotency or side effects, leaving some aspects unspecified.

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 extremely concise (two sentences plus parameter list) and front-loaded with the core action. Every sentence adds value, with no redundant or extraneous 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 tool with a single parameter and an existing output schema, the description fully covers the action, condition, and parameter meaning. No additional return value explanation is needed, and the description is complete for agent understanding.

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 input schema only describes device_id as a string with 0% coverage. The description adds 'Controller UUID,' clarifying the expected format beyond the schema. This adds significant meaning, compensating for the lack of schema documentation.

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 clearly states the action 'Skip to the next zone' and the context 'in the currently-running schedule.' This verb+resource combination effectively distinguishes it from sibling tools like skip_schedule, which skips an entire schedule, and stop_watering, which stops all watering.

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 provides a clear usage condition: 'Does nothing if no schedule is running.' This tells the agent when the tool is applicable. However, it does not explicitly compare to alternatives or mention when not to use it, which would improve 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?

The description adds value beyond annotations: it explains that the flag applies only to the next occurrence and details the effect of 'disabled=true/false'. Annotations already indicate it's a non-read, non-destructive, idempotent operation, so the description complements these without contradiction.

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

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

The description is concise, with the purpose stated in the first line. The addition of a usage example and parameter list is justified, though the parameter documentation could be more integrated. Overall, it is well-structured and 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?

Given the tool's simplicity (two required parameters, boolean operation) and the presence of an output schema, the description fully covers what the tool does, its scope ('next occurrence'), and parameter semantics. No gaps remain for agent understanding.

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 fully compensates by providing an 'Args' section that explains both 'schedule_id' (UUID) and 'disabled' (True to skip, False to re-enable), adding essential meaning absent from the input schema.

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

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

The description clearly states the tool toggles the skip-next-run flag on a schedule, using a specific verb ('Toggle') and resource ('skip-next-run flag'), which distinguishes it from sibling tools like 'update_schedule' or 'run_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 provides no guidance on when to use this tool versus alternatives such as 'run_schedule' or 'skip_current_zone'. It only describes the effect, leaving the agent to infer usage context without explicit exclusions or recommendations.

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

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

The description adds behavioral context beyond annotations: it states that zones run 'in sequence' and defines the zones format. Annotations indicate readOnlyHint=false (so mutation is expected) and destructiveHint=false (not destructive). The description aligns with these (starting a run is a mutation but not destructive). However, it does not disclose potential side effects (e.g., if a run is already active, or what happens to overlapping schedules). The behavioral transparency is adequate but not exhaustive.

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

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

The description is well-structured: a one-line summary followed by a detailed parameter breakdown. It is informative but slightly verbose (e.g., repeating 'zones' explanation twice). However, it front-loads the purpose and uses clear formatting (args list). It earns its length by adding value, but could tighten redundancy slightly.

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

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

Given the tool's complexity (5 parameters, manual run initiation) and the presence of an output schema (so return values are not required), the description is complete. It covers all parameters, explains the zones format concretely, references a sibling tool (list_zones) for required data, and describes the cycle-soak functionality. No gaps are apparent.

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 description provides detailed semantics beyond the input schema, which only gives types and defaults. It explains that zones is a list of dicts with specific keys ('zone_number' and 'duration'), specifies that zone_number is a 1-based hardware slot (not UUID) found via list_zones, and describes the role of cycle_soak and its associated parameters. This adds critical meaning, especially since the schema defines zones as 'array of object' with no inner structure validation.

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 clearly states 'Start a manual run of one or more zones in sequence,' specifying the verb (start), resource (zones), and context (manual, sequential). This distinguishes it from sibling tools like run_schedule (which starts scheduled runs) and stop_watering (which stops current runs). The explicit mention of 'manual run' differentiates it from schedule-based actions, and the details about zone numbering via list_zones further clarify the resource.

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 provides context on when to use the tool (e.g., for a manual run) and hints at prerequisites (finding zone_number via list_zones). However, it does not explicitly state when not to use it or mention alternatives (e.g., run_schedule for scheduled runs). The description lacks exclusion criteria or comparative guidance, leaving the agent to infer usage boundaries.

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 indicate idempotentHint=true and destructiveHint=false. Description adds no-op behavior, consistent with idempotency. No further behavioral details (e.g., prerequisites, side effects).

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

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

Two sentences plus an args line, no fluff. Front-loaded with action. Every part 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?

Given low complexity (1 param, output schema exists), description covers action, no-op, and parameter. Could mention differentiation from pause/stop for completeness.

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

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

Schema has 0% description coverage, but description explicitly states 'device_id: Controller UUID', adding meaning beyond schema's generic title 'Device Id'. Clear and valuable.

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?

Description clearly states 'Stop all watering' with specific verb and resource. Distinguishes from siblings like pause_watering (temporary pause) and resume_watering (resume).

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?

Description mentions no-op behavior when nothing is running, which aids usage. However, lacks explicit guidance on when to use stop versus pause or other alternatives.

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

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

Annotations provide readOnlyHint=false, destructiveHint=false; description adds critical detail about the partial-merge, non-destructive nature (except zone removal), and that omitting args leaves them untouched. No contradiction.

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

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

Front-loaded with summary and behavior, followed by a concise recommendation, then a well-organized Args list. Every sentence is informative with 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?

Given the complexity (21 parameters, no output schema shown), the description covers all essential aspects: purpose, behavior, parameter semantics, and usage recommendations. Output schema exists but does not need to be described.

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 fully compensates by providing detailed explanations for all 21 parameters, including format constraints, mutual exclusivity, and special values (e.g., 'Pass [] to clear').

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 clearly states 'Partial-merge update of an existing schedule' which is a specific verb+resource. It further explains the overlay behavior and references sibling tools for field meanings, effectively distinguishing from create/preview.

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?

Recommends calling 'get_schedule first to review current values', providing clear before-use guidance. It implicitly distinguishes from create_schedule and preview_schedule but lacks explicit when-not-to-use exclusions.

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