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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes a critical behavioral trait: that the operation is blocked without user confirmation. However, it doesn't mention other potential behavioral aspects like error conditions, response format, or side effects on other home automation 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?

The description is perfectly concise with two sentences that each serve a distinct purpose: stating the action and stating the critical requirement. It's front-loaded with the core function and wastes no words while providing essential 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 2-parameter tool with no annotations and no output schema, the description provides good coverage of the activation behavior and confirmation requirement. However, it doesn't explain what 'activating a scene' actually does in Home Assistant context or what the expected outcome looks like, leaving some contextual 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 description coverage is 100%, so the schema already fully documents both parameters. The description adds no additional parameter semantics beyond what's in the schema descriptions, which already explain entity_id format and the required confirmation. This meets the baseline for high schema 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 clearly states the specific action ('Activate a scene') and resource ('in Home Assistant'), distinguishing it from siblings like scene_create, scene_delete, or scene_list. It uses precise verb+resource language that leaves no ambiguity about the tool's function.

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 when to use this tool ('REQUIRES user_confirmed=true - user must explicitly request scene activation'), providing clear prerequisites and conditions for invocation. This gives the agent concrete guidance on the mandatory confirmation requirement before using this 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?

With no annotations provided, the description carries full burden and does an excellent job disclosing key behavioral traits: it specifies the tool only affects current state (not saved to scenes), requires explicit user confirmation (user_confirmed=true), and mentions that without confirmation 'operation is blocked.' It doesn't cover rate limits or error behaviors, but provides substantial operational 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 perfectly structured and concise: three sentences with zero waste. First sentence states purpose and capabilities, second clarifies critical limitation, third specifies mandatory requirement. Every sentence earns its place with essential information 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?

For a mutation tool with no annotations and no output schema, the description provides excellent context about the tool's behavior, limitations, and requirements. It covers the critical distinction from scene-saving operations and the mandatory confirmation requirement. The main gap is lack of information about return values or error conditions, but given the rich parameter schema and clear behavioral disclosure, it's quite 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 100%, so the schema already documents all 8 parameters thoroughly. The description adds minimal parameter semantics beyond the schema - mainly emphasizing the 'user_confirmed' requirement. It doesn't provide additional context about parameter interactions or usage patterns beyond what's in the schema descriptions.

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

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

The description clearly states the specific action ('controlling lights') with detailed operations (turn on/off, set brightness, RGB color, etc.) and distinguishes it from siblings by emphasizing it's for current state changes only, not scene saving. It explicitly positions itself as 'PREFERRED for controlling lights' among the scene-related tools.

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

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

The description provides explicit usage guidance: 'PREFERRED for controlling lights' indicates when to use it, 'This only changes the light's current state - it does NOT save to any scene' clarifies when NOT to use it (vs. scene-saving tools), and 'REQUIRES user_confirmed=true' specifies a critical prerequisite. It also references sibling tool 'scene_show_lights' for seeing available effects.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the destructive nature (turning off ALL lights), the safety mechanism (user_confirmed requirement), and optional scene creation behavior. It doesn't mention error handling or rate limits, but covers the core behavioral traits well.

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 perfectly front-loaded with the core action first, followed by optional functionality and critical requirement. Every sentence earns its place: first states the main action, second adds optional scene creation, third establishes the safety requirement. No wasted words.

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

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

For a destructive tool with no annotations and no output schema, the description provides strong context about the tool's behavior and safety requirements. It could benefit from mentioning what happens when lights are turned off (e.g., whether previous states are saved) or error conditions, but covers the essential aspects well given the complexity.

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 100% schema description coverage, the baseline is 3. The description adds value by emphasizing the critical importance of the user_confirmed parameter ('REQUIRED: user must explicitly request blackout') and clarifying the tool's primary purpose beyond what the schema provides, though it doesn't elaborate on exclude or create_scene parameters beyond schema descriptions.

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

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

The description clearly states the specific action ('Turn off ALL lights') and distinguishes it from siblings by focusing on blackout functionality rather than scene activation, adjustment, or management. It goes beyond the tool name by specifying the scope ('ALL lights') and optional scene creation.

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 when to use this tool (for blackout operations) and includes a critical prerequisite ('REQUIRES user_confirmed=true - user must explicitly request blackout'). It differentiates from siblings by focusing on mass light control rather than scene-specific operations like scene_activate or scene_configure.

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?

No annotations are provided, so the description carries the full burden. It indicates this is a configuration/setup tool that establishes connection parameters, but doesn't disclose behavioral details like whether configuration persists across sessions, what happens on invalid credentials, or error handling. It adds some context about the environment variable alternative but lacks operational details.

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 with zero waste - the first states the purpose, the second provides critical usage guidance. Every word earns its place, and the most important information (that this is required before using other tools) is front-loaded in the second sentence.

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

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

For a configuration tool with 2 parameters and 100% schema coverage, the description provides adequate context about its role in the tool ecosystem. It explains the prerequisite relationship with sibling tools and mentions alternative configuration methods. However, without annotations or output schema, it could benefit from more behavioral details about what 'configure' actually does operationally.

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

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

Schema description coverage is 100%, providing complete documentation for both parameters (url and token). The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline for high schema coverage without adding extra semantic value.

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 specific action ('Configure the Home Assistant connection') and resource ('for the Scene MCP server'), distinguishing it from all sibling tools which perform scene operations rather than configuration. It explicitly identifies this as a setup/initialization 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 provides explicit when-to-use guidance: 'Required before using other scene_ tools if not already configured via environment variables.' It clearly states the prerequisite relationship with sibling tools and mentions the alternative configuration method (environment variables).

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

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

With no annotations provided, the description carries full burden and does well by disclosing behavioral requirements: the mandatory user interaction for mode selection, the prerequisite step of showing current lights, and the distinction from update operations. It doesn't mention error conditions or response format, but covers key behavioral 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?

The description is appropriately sized and front-loaded with the core purpose. Every sentence adds value: the first states the action, the second provides usage rules, the third gives prerequisites, and the fourth specifies exclusions. It could be slightly more concise by combining some instructions.

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 creation tool with no annotations and no output schema, the description provides strong contextual completeness. It covers when to use, prerequisites, behavioral constraints, and sibling differentiation. The main gap is lack of information about return values or error cases, but given the good usage guidance, it's mostly 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 100%, so the schema already documents all parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it emphasizes that mode 'MUST be asked from user before saving' but doesn't provide additional meaning for name, entity_ids, or icon. Baseline 3 is appropriate when schema does the heavy lifting.

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 specific action ('Create a NEW scene') and resource ('in Home Assistant'), distinguishing it from siblings like scene_update for updates. It explicitly defines the scope as new scene creation only, not updates.

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 explicit when-to-use guidance: 'ONLY call when user EXPLICITLY asks to create/save a NEW scene' and 'Do NOT call this to update existing scenes - use scene_update for that.' It also specifies prerequisites (show current lights, ask for mode) and names the alternative tool (scene_update).

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a deletion operation but doesn't mention whether it's reversible, what permissions are required, if it affects related entities, or what happens on success/failure. For a destructive operation, this is a significant gap in transparency.

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, clear sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately understandable without unnecessary elaboration.

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 destructive tool with no annotations and no output schema, the description is incomplete. It doesn't address critical context like what 'delete' entails (permanent removal?), error conditions, or return values. Given the complexity of deletion operations, more behavioral details are needed.

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 has 100% description coverage, with the 'entity_id' parameter clearly documented. The description adds no additional parameter semantics beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting.

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 ('Delete') and resource ('a scene from Home Assistant'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'scene_configure' or 'scene_update', but the action is specific enough to imply distinction.

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 like 'scene_update' or 'scene_configure', nor does it mention prerequisites (e.g., needing an existing scene). It simply states what the tool does without contextual usage information.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it performs diagnostic tests, identifies specific problems (null values, missing lights), provides recommendations, and critically discloses that connectivity tests toggle lights and require user confirmation. This covers safety and mutation aspects well for a diagnostic tool, though it doesn't mention rate limits or error handling.

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 highly concise and well-structured in two sentences. The first sentence front-loads the core purpose and key activities. The second sentence provides critical usage guidance for the parameters. Every word earns its place with no redundancy or 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?

For a diagnostic tool with 2 parameters, 100% schema coverage, and no output schema, the description is quite complete. It explains what the tool does, when to use it, and critical behavioral constraints. The main gap is lack of information about return values or output format, but given the tool's diagnostic nature and no output schema, the description does well to cover purpose, usage, and safety considerations.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds value by explaining the relationship between test_connectivity and user_confirmed ('REQUIRES user_confirmed=true because it toggles lights'), which provides context beyond the schema's individual parameter descriptions. However, it doesn't add semantic meaning to the parameters themselves beyond what the schema states.

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

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

The description clearly states the tool's purpose: 'Diagnose lights and scenes' with specific activities like testing connectivity, identifying problems, and providing recommendations. It distinguishes from siblings like scene_fix or scene_configure by focusing on diagnostic analysis rather than repair or configuration. However, it doesn't explicitly differentiate from scene_show_lights or scene_history which might also reveal diagnostic information.

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 explicit usage guidelines: 'If test_connectivity=true, REQUIRES user_confirmed=true because it toggles lights.' This clearly states when a parameter is required and why, helping the agent avoid accidental light changes. It also implies this tool is for diagnostic purposes rather than activation or modification (which are handled by siblings like scene_activate or scene_update).

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

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

With no annotations provided, the description carries full burden and does well by disclosing important behavioral traits: it specifies that 'test_scene action REQUIRES user_confirmed=true because it changes lights' (safety requirement), mentions 'restore from backup' (recovery capability), and indicates interactive testing with user feedback. However, it doesn't mention potential side effects like scene disruption or performance impact.

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 appropriately sized with two sentences that each earn their place. The first sentence establishes the core purpose and capabilities, while the second provides critical safety information about the test_scene action. It could be slightly more front-loaded by leading with the safety requirement.

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 (multiple actions with different behaviors) and no annotations or output schema, the description does well by explaining the tool's relationship to scene_diagnose, listing fix capabilities, and specifying the critical safety requirement for test_scene. However, it doesn't describe what happens after fixes are applied or potential error conditions.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some value by explaining the relationship between 'test_scene' and 'user_confirmed' parameters, but doesn't provide additional semantic context beyond what's already documented in the schema descriptions for each 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?

The description clearly states the tool's purpose: 'Fix problems found by scene_diagnose' with specific verb+resource. It distinguishes from siblings by explicitly mentioning its diagnostic relationship with 'scene_diagnose' and listing specific fix capabilities (null values, missing lights, backup restoration, interactive testing).

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 explicit when-to-use guidance: 'Fix problems found by scene_diagnose' establishes the primary use case. It also specifies when-not-to-use alternatives by mentioning specific capabilities (fix null values, add missing lights, restore from backup, interactive testing) that differentiate it from other scene manipulation tools like scene_activate or scene_update.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool 'shows what the scene looked like before recent updates or deletions' but lacks details on permissions needed, whether it's read-only (implied by 'view'), rate limits, pagination beyond the limit parameter, or what format the history entries take. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

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 efficiently structured in three sentences: first states purpose, second elaborates functionality, third provides usage context. Every sentence adds value with zero waste. It's appropriately sized and front-loaded with the core purpose.

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 2 parameters with full schema coverage but no annotations and no output schema, the description provides adequate basic context (purpose and usage) but lacks completeness. It doesn't explain what the output looks like (history entries format), behavioral constraints, or error conditions. For a read-only history tool, this is minimally viable but has 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?

Schema description coverage is 100%, so the schema already documents both parameters (scene_id and limit) thoroughly. The description adds no parameter-specific information beyond what's in the schema. Baseline score of 3 is appropriate when the schema does all the work, though the description doesn't compensate with additional context like default behaviors or examples.

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: 'View history of scene changes (snapshots)' with specific verbs ('view', 'shows') and resource ('scene changes'). It distinguishes from siblings like scene_list (which likely shows current scenes) by focusing on historical snapshots. However, it doesn't explicitly differentiate from all siblings (e.g., scene_diagnose might also involve debugging).

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 implied usage context: 'Useful for debugging or understanding what changed.' This suggests when to use it (for debugging/change analysis) but doesn't explicitly state when NOT to use it or name alternatives among siblings. No guidance on prerequisites or comparisons to similar tools like scene_diagnose.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. While 'List' implies a read-only operation, the description doesn't specify whether this returns all scenes at once or uses pagination, what format the output takes, or any rate limits or authentication requirements. The description is too minimal for a tool with no annotation support.

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, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized for a simple listing operation and gets straight to the point.

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 no output schema and no annotations, the description is insufficiently complete. For a listing operation among 12 sibling tools, the description should provide more context about what 'List all scenes' means operationally - whether it returns summaries or full details, how results are structured, and how it differs from other listing-like siblings.

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

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

The tool has zero parameters, and schema description coverage is 100% (empty schema is fully described). The description doesn't need to explain any parameters, so it meets the baseline expectation for a parameterless tool. No additional parameter information is required or provided.

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 ('List') and resource ('all scenes from Home Assistant'), making the purpose immediately understandable. However, it doesn't distinguish this tool from potential sibling alternatives like 'scene_history' or 'scene_show_lights' that might also list scenes in different ways.

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 the 11 sibling tools. There's no mention of alternatives, prerequisites, or specific contexts where this listing operation is appropriate versus other scene-related operations.

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?

No annotations are provided, so the description carries full burden. It discloses key behavioral traits: it's safe and read-only, returns detailed light data, and includes important clarifications about color modes and what not to report. However, it doesn't mention potential limitations like rate limits, error handling, or authentication needs.

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 and front-loaded with the core purpose, followed by usage guidance and return details. Slightly verbose in listing return fields, but every sentence adds value (e.g., clarifying color modes).

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

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

Given no annotations and no output schema, the description compensates well by detailing return values and behavioral context. It covers the tool's purpose, usage, and output semantics adequately, though it could benefit from mentioning any prerequisites or error scenarios.

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

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

Schema description coverage is 100%, so the schema already documents the optional 'filter' parameter. The description doesn't add any parameter-specific details beyond what's in the schema, maintaining the baseline score of 3.

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

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

The description clearly states the specific action ('Shows ALL Home Assistant lights with FULL details'), the resource ('lights'), and distinguishes it from siblings by emphasizing it's read-only and for viewing states rather than modifying scenes or lights like scene_adjust_light or scene_activate.

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 when to use ('Use this to answer questions about light states, colors, brightness') and when not to use ('Does NOT change anything'), with clear context for querying light information versus other scene-related tools that modify or configure scenes.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool fetches all scenes and updates the local backup, implying a read-and-write operation. However, it lacks details on behavioral traits like error handling, performance implications (e.g., time to sync), or side effects (e.g., whether it overwrites or merges backups). The description adds some context but is incomplete for a mutation tool.

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

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

The description is two sentences with zero waste: the first states the action and scope, and the second provides usage guidance. It is front-loaded with the core purpose and efficiently structured, with every sentence earning its place by adding distinct 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 tool's complexity (a mutation operation with no annotations and no output schema), the description is partially complete. It covers the purpose and usage well but lacks details on behavioral aspects like what 'updates local backup' entails (e.g., overwrite, merge, error handling) or the response format. For a tool that modifies data, more transparency would be beneficial.

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 has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, focusing instead on the tool's purpose and usage. This meets the baseline for tools with no parameters, as there's nothing to compensate for.

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 specific action ('Sync local backup with Home Assistant') and resource ('scenes from HA'), distinguishing it from siblings like scene_list (which only lists) or scene_update (which updates individual scenes). It explicitly mentions fetching all scenes and updating the local backup to match, providing a precise verb+resource+scope combination.

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 when to use this tool: 'Useful for ensuring backup is current before making changes.' This provides clear context for usage (pre-change backup synchronization) and implicitly distinguishes it from alternatives like scene_list (for viewing) or scene_update (for modifying individual scenes), though it doesn't name specific 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?

With no annotations provided, the description carries full burden and adds valuable behavioral context: it explains the exclusive mode behavior ('captures ALL lights (on lights with settings, off lights as 'off')'), which clarifies how the tool handles light states beyond what the schema's enum description provides. However, it doesn't mention permissions, rate limits, 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?

Three sentences with zero waste: first states purpose, second gives critical usage rule, third explains exclusive mode nuance. Each sentence earns its place by adding distinct value, and the most important guidance is front-loaded.

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

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

For a mutation tool with no annotations and no output schema, the description does well by providing clear purpose, strong usage rules, and behavioral context about exclusive mode. However, it doesn't explain what the tool returns or potential side effects beyond the mode explanation, leaving some gaps for a write operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context about exclusive mode behavior ('captures ALL lights') that complements the schema's enum description, but doesn't provide additional syntax, format, or examples beyond what's already documented in the schema properties.

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 ('update') and resource ('existing scene') with specific scope ('with current light states'). It distinguishes from siblings like scene_create (create new), scene_activate (activate), and scene_adjust_light (adjust individual lights) by focusing on saving current states to an existing scene.

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?

Explicit guidance is provided: 'ONLY call this when user EXPLICITLY asks to save/update a scene. Do NOT call automatically after adjusting lights.' This clearly defines when to use (explicit user request) and when not to use (automatic updates), helping distinguish from scene_adjust_light for temporary adjustments.

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