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

No annotations exist, so the description must convey behavioral traits. It fails to indicate whether actions are read-only or mutating, side effects, or authorization needs. The list of actions implies some are queries, but safety_audit or orphans could be destructive.

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 but poorly structured; it uses a colon and comma-separated list without clear grouping. While front-loaded with 'Home-wide analysis', the bulk is dense and hard to scan.

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 (9 actions, 4 parameters, no output schema, no annotations), the description lacks critical details such as return values, prerequisites, and the full scope of each action. It leaves significant gaps for agent decision-making.

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 clarifies which parameters apply to which actions (e.g., 'days' for stale_items, 'roomName' for find_equipment), adding value beyond the schema's brief descriptions. This reduces ambiguity for parameter usage.

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 'Home-wide analysis' and enumerates specific actions (health, safety_audit, etc.), making the tool's purpose clear. However, it lacks a main verb and could be more explicit about the general 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?

No guidance is provided on when to use this tool vs. alternatives like 'manage_item' or 'query_things'. Without usage context, the agent may choose the wrong 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?

No annotations are provided, so the description must fully disclose behavioral traits. It mentions 'shadow_run (dry-run preview)' hinting at non-destructive behavior, but does not state side effects, authorization needs, rate limits, or error conditions for other actions. The description is insufficient for an agent to understand the full behavioral implications.

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 sentence that front-loads the tool's purpose and then lists all actions with concise summaries. Every part is essential, no waste. Ideal length for scanning.

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 has 7 parameters, 5 actions, and no output schema. The description covers the actions adequately but lacks information about return values, error handling, or required permissions. It is functionally complete for what each action does but misses behavioral and output context.

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

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

Schema description coverage is 86%, high, so baseline is 3. The description adds no parameter meaning beyond listing actions; the schema itself documents parameter usage with 'Used by:' notes. Thus the description does not elevate parameter understanding 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?

The description clearly states 'Automation generation and testing' and enumerates five specific actions (generate_rule, discover_patterns, shadow_run, simulate, validate_rule). It provides a verb+resource mapping for each, making the tool's purpose distinct from sibling tools like manage_rule or query_rules. However, it does not explicitly contrast with siblings.

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?

Each action is briefly described (e.g., 'from NL', 'temporal correlation', 'dry-run preview', 'predict outcome + rule chains', 'JS syntax check'), which implies usage context. However, no explicit guidance on when to use this tool versus alternatives (e.g., manage_rule), nor any exclusion criteria or prerequisites.

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

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

No annotations are provided, and the description does not disclose behavioral traits like side effects, required permissions, or device state dependencies. The tool performs mutations but details are missing.

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 concise sentence that lists actions. It could be more structured but is not verbose.

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 two-parameter tool, the description covers the core purpose and actions but lacks usage guidance and behavioral context, leaving gaps for an 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 50% (action lacks description). The description lists actions, but these are already present in the schema's enum. No new meaning is added for either 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 states the verb 'control' and resource 'media player equipment item', and lists specific actions. However, it does not differentiate from sibling tools like send_command or manage_thing.

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 such as send_command or manage_thing. No context on prerequisites or limitations.

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 reveals that 'explain' returns forensic state, rules, and history, and 'topology' returns a Mermaid home graph. However, it omits details like whether the tool is read-only, requires authentication, or what happens on failure (e.g., item not found).

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 (two sentences) and front-loads the primary purpose ('Item diagnostics'). The second sentence structures the actions clearly, though a bit run-on. Nearly all words are informative, with minimal 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?

Given the lack of an output schema and moderate complexity, the description is insufficient. It fails to explain the return format for either action (e.g., structure of forensic details, Mermaid syntax, error states). Users cannot anticipate what data they receive, which is critical for a diagnostic 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 adds meaning beyond the schema. For 'action', it explains the two enum values ('explain' and 'topology') with their functions, which the schema only lists as options. For 'itemName', it notes it is required for 'explain', exceeding the schema's own description. However, it does not clarify the format or source of item 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 is for item diagnostics and specifies two distinct actions: 'explain' (forensic state, rules, history) and 'topology' (Mermaid home graph). This differentiates it from sibling tools like 'analyze_home' (whole-home analysis) and 'query_items' (simple listing), making the purpose unambiguous.

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

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

No usage guidance is provided. The description does not indicate when to use this tool versus alternatives like 'resolve_item', 'remediate', or 'manage_item'. There is no mention of prerequisites, typical scenarios, or situations where other tools would be 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?

The description reveals parallel execution behavior but fails to disclose failure handling, ordering, rate limits, or authentication needs. With no annotations provided, the description carries the burden of behavioral disclosure but is insufficiently detailed.

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 at two sentences, front-loading the key action and use cases. Every word 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 complexity (batch execution with nested object parameters), no output schema, and no annotations, the description is too brief. It does not cover error behavior, execution guarantees, or parameter formatting essentials, making it incomplete for reliable use.

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 descriptions for 'command' and 'state' but not for 'itemName'. Schema description coverage is effectively 0% as per context, and the description does not elaborate on the parameter structure or usage beyond the schema, leaving the agent to infer details from the schema alone.

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 'Execute multiple commands in parallel' and provides concrete use cases ('Goodnight', scene-like, multi-device actions). This distinguishes it from siblings like send_command (single command) and manage_scene (scene management).

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 mentions when to use the tool ('Use for 'Goodnight', scene-like, or multi-device actions.'), giving clear context. However, it does not specify when not to use it or mention alternative tools, leaving slight ambiguity.

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, and the description does not disclose any behavioral traits such as whether the tool is read-only, requires authentication, or has side effects. The description only mentions the output format, leaving the agent unaware of potential implications.

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, front-loading the purpose and usage guidance without any unnecessary 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 tool with no parameters and no output schema, the description adequately explains the tool's output (Markdown guide) and usage context. However, it lacks details on limitations or scope of the 'room-by-room' coverage, which could be considered a minor gap.

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

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

Tool has no parameters, and schema coverage is 100%. The description does not need to add parameter details, fulfilling the baseline for zero-parameter tools.

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 generates a 'Full room-by-room Markdown guide of the home', using a specific verb and resource, and distinguishes itself from the sibling tool 'initial_discovery' by noting it should not be used as a first step.

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 instructs when to use (layout exploration, explicit request for overview) and when not to (not a first step, use initial_discovery instead), providing clear context and 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?

No annotations are provided, so the description must disclose behavioral traits. It only says 'snapshot,' which implies a read operation, but does not explicitly state read-only, authentication needs, rate limits, 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 a single, concise sentence that effectively communicates the tool's purpose without extraneous 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?

Given the tool has no parameters and no output schema, the description adequately lists what the snapshot includes (items, things, rooms, health). It could mention read-only nature or typical use cases, but is mostly complete for this 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?

The tool has zero parameters, so the schema is fully covered. Without parameters, the description cannot add meaning beyond the schema, but a baseline of 4 is appropriate as no additional parameter info is needed.

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 provides a 'high-density snapshot' covering items, things, rooms, and health. It uses a specific verb ('get') and resource ('system summary'), and distinguishes from sibling tools like 'query_items' or 'manage_system' by indicating an aggregated overview.

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 given on when to use this tool versus alternatives. It does not specify that it is best for a quick overview, nor does it mention when to use more specific tools for detailed 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?

No annotations are provided, but the description implies a read-only bootstrap operation. It discloses the output content and scope, though it does not explicitly state that it has no side effects. The lack of destructive hint in context signals is consistent.

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, no fluff. Front-loaded with purpose and includes essential usage constraints. 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 no parameters and no output schema, the description covers the tool's purpose, output summary, and usage constraints. It also addresses sibling tools, making it 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 tool has zero parameters and schema description coverage is 100%. The description adds no param info because none exist, meeting the baseline expectation for a parameterless tool.

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: a one-shot bootstrap that returns a compact guidance context with a room-grouped quick-reference of items. It specifies the output includes name, type, and live state, and distinguishes it from sibling tools by name.

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 directs to call ONCE on first contact and advises against calling generate_home_blueprint or get_system_summary, providing clear when-to-use and when-not-to-use 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?

No annotations are provided, so the description must carry the burden of behavioral transparency. It discloses the actions but fails to describe their side effects, such as what happens on deletion, whether operations are reversible, or authorization requirements.

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 and front-loads the purpose. However, the list of actions is redundant with the schema enum, and the structure could better guide the user on action-parameter relationships.

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 (8 parameters, no output schema, no annotations), the description is overly brief. It lacks information on required parameters for each action, response format, or error conditions, leaving significant 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?

The input schema already covers 75% of parameters with 'Used by' descriptions, so the baseline is 3. The tool description adds no extra parameter semantics beyond listing the actions, which are already in the schema's enum.

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 'Modify' and the resource 'items', and lists the possible actions. However, it does not differentiate from sibling tools like manage_thing or manage_link, which share a similar 'manage' prefix and could cause confusion.

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 the tool is used to modify items with various actions, but it provides no explicit guidance on when to use this tool versus alternatives. No when-not or alternative tools are mentioned.

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 exist, so the description must fully disclose behavior. It only lists actions without mentioning side effects, persistence, error handling, or response format. The tool is essentially opaque.

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 sentence with a clear purpose and an enumerated list of actions. 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?

Given 6 parameters and no output schema, the description is too sparse. It does not explain what each action does, when to use each, or what the tool returns. The tool is incomplete from a contextual standpoint.

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 83%, which is high. The description adds minimal value beyond the schema (just restating the action enum). Base score 3 is appropriate.

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 manages item-channel links and enumerates four actions (list, link, unlink, configure). This distinguishes it from sibling tools like manage_item or manage_thing.

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 vs alternatives, no prerequisites, and no context for each action. The agent must infer usage from the action enum alone.

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

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

With no annotations, the description must disclose behavioral traits. It mentions logs are on a remote server and the need to call set_folder first, but it does not explain error handling, rate limits, or what happens if the folder is not set.

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 short and front-loaded with the purpose. However, the list of actions is redundant with the schema and could be integrated more efficiently.

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 lacks details about return values, pagination, or log format. Without an output schema, this information is crucial for an agent to correctly use the tool. It also omits the logType parameter context.

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

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

Schema description coverage is 86%, so the schema already documents most parameters. The description adds value by instructing to ask for the path, but it does not elaborate on parameter usage or formats beyond what the schema provides.

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

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

The description clearly states it's for OpenHAB log access and lists the available actions. However, it does not explicitly differentiate it from sibling tools like diagnose_item or manage_system, though no other sibling specifically manages logs.

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 prerequisite: 'ask the user for the path and call set_folder first.' It lists actions but does not specify when to use each action or when not to use this tool, nor does it mention alternatives among siblings.

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 does not disclose behavioral traits such as mutability (e.g., 'store_data' is a write operation), required permissions, or side effects. The minimal description adds no behavioral context beyond what the schema implies.

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 short: one sentence plus a list. It is front-loaded but lacks detail. It is not overly verbose, but it misses important information that would justify its length. It earns a 3 as minimally acceptable.

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 7 parameters, 5 actions, no output schema, and no annotations, the description is insufficient. It does not explain return values, error handling, or relationships between parameters. The schema partially compensates, but the description alone does not provide a complete picture for an agent to invoke the tool correctly.

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

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

Schema description coverage is 86%, which is high, so the baseline is 3. The description adds no additional meaning beyond the schema; it only lists actions that are already in the enum. The parameter descriptions in the schema already tell which params are used by which actions, so the description does not improve 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 states the tool handles 'Persistence data operations' and lists specific actions (services, get_data, store_data, etc.), making the purpose clear. However, the phrase 'Persistence data operations' is somewhat generic; a more specific verb+resource would improve clarity. It does distinguish from siblings like 'manage_item' or 'manage_logs'.

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 sibling tools. The description simply lists sub-actions without mentioning prerequisites, alternatives, or exclusion criteria. An agent would not know when to choose this over 'manage_item' or 'manage_logs' for data 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?

With no annotations, the description carries full burden for behavioral disclosure. It lists actions that modify state (delete, disable) but does not mention side effects, permissions, rate limits, or whether operations are reversible. The description is too sparse.

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 sentence plus an enumerated list, making it efficient and front-loaded. Every element is relevant, though it could be slightly expanded without becoming verbose.

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 multi-action nature (6 actions), nested object parameter, and lack of output schema, the description is incomplete. It fails to explain return values, error conditions, or prerequisites (e.g., ruleUID required for non-create actions). Significantly more context is 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 schema already describes ruleUID and ruleData with inline descriptions (67% coverage). The description only enumerates the action enum, adding no extra parameter semantics beyond what the schema provides. Baseline score of 3 is appropriate.

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 indicates the tool manages automation rules and lists specific actions (create, update, delete, enable, disable, run). It is not a tautology and differentiates from sibling tools that manage other resources like items or scenes.

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 query_rules. The agent must infer that this tool is for writing operations, but the description lacks explicit context.

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

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

No annotations provided, so description must fully disclose behavior. It only lists actions without explaining side effects, such as whether existing scenes are overwritten or if capture affects current states. Missing behavioral traits like idempotency or required preconditions.

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?

Single sentence, very concise, with information front-loaded. No unnecessary words. Every part serves a 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 simple structure (3 params, no output schema), description covers the core purpose but lacks details about error handling, persistence, or interaction with other tools. Adequate for basic understanding but not fully self-contained.

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 67% but description adds little beyond the schema. 'action' is mentioned with enum values, but 'name' and 'itemNames' are not elaborated beyond what schema says. The description does not clarify parameter roles 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?

Description clearly states it manages named scenes with two actions: capture (save states) and activate (restore). Verb and resource are specific. While no explicit differentiation from siblings, 'scene management' is unique among listed 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?

No guidance on when to use this tool versus alternatives like manage_item or send_command. No context about prerequisites or typical use cases.

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 present, so the description bears full responsibility for disclosing behavioral traits such as side effects, authorization needs, or destructive potential. The description provides none of this information, listing only action names.

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 run-on sentence with a long list of actions. It lacks structure, is not front-loaded with a clear purpose, and contains no paragraph breaks or bullet points. Every sentence should earn its place; here, the list is exhaustive but not helpful.

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 9 parameters and no output schema, the description should explain return values, usage patterns, or common workflows. Instead, it only lists action names and parameter associations. The tool is highly complex but the description provides almost no contextual 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 coverage is 89%, so the baseline is 3. The description does add a list of which parameters are used by which actions (e.g., 'Used by: service_config_get'), but this information is already present in the schema's parameter descriptions. The description does not provide additional meaning beyond what the schema already conveys.

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 lists multiple actions but fails to state a unified purpose. It reads as an enumeration of sub-commands rather than a clear verb+resource. This makes it hard for an agent to understand when to invoke this tool versus siblings like 'manage_logs' or 'get_system_summary'.

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 or when to prefer alternatives. The description merely lists actions without context, leaving the agent to guess the appropriate use case among 24 sibling tools.

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 exist, and the description does not disclose behavioral traits beyond the listed actions (e.g., whether deletes are irreversible, or if enables have side effects). The agent gains minimal insight into the tool's runtime behavior.

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

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

The description is extremely concise, using a single sentence to convey the tool's purpose and actions. No unnecessary words are present. It is well front-loaded but could benefit from slightly more structure.

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, multiple actions, no output schema) and the existence of many sibling tools, the description lacks essential context like what constitutes a 'thing', which action applies when, or any return behavior. It is incomplete for effective use.

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 high (80%), and the description adds no new information beyond repeating the action enum. The baseline of 3 is appropriate since the schema already documents the parameters adequately.

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

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

The description states the tool manages 'things' and lists possible actions (create, update, delete, enable, disable, configure), providing a clear verb-resource pair. However, it does not differentiate what a 'thing' is compared to siblings like manage_item or manage_rule, making the purpose somewhat vague in 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?

There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or scenarios. The description simply lists actions without context, leaving the agent to infer usage independently.

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 only lists sub-actions with no mention of side effects, permissions, or state changes, leaving behavior completely opaque.

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 but at the expense of clarity. It is simply a run-on list of terms without structure, which fails to convey meaning efficiently.

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 10 parameters and many sub-actions (16 enum values), the description provides no explanation of what each action does, what the tool returns, or any prerequisites. It is severely 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?

Schema coverage is 90%, so baseline is 3. The description adds minimal value beyond the schema, which already documents which parameters belong to which actions. No extra semantic context is 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 is a list of action names and related keywords, but fails to state a coherent purpose. It reads as a catalog of sub-operations without a unifying verb+resource statement, making it vague.

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 siblings like manage_item or manage_thing. The description does not indicate scenarios or prerequisites for invoking the 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, the description carries the full burden. It reveals that health returns 'SSE/cache metrics' and prompt_context returns 'AI priming context', but does not disclose whether operations are read-only, require special permissions, or have side effects. The behavioral profile is minimally covered.

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

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

A single, well-structured sentence that lists the three actions with parenthetical explanations. Every word is informative and necessary; 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?

The description adequately explains the one parameter and its options. However, without an output schema, it omits what the return data looks like for each action, which is important for an agent to interpret results. It's functional but could be more complete.

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

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

The schema has 0% description coverage, but the description adds meaning by explaining each enum value (e.g., 'health (SSE/cache metrics)', 'prompt_context (AI priming context for this home)'). This compensates for the empty schema, though more detail on the actions' outputs would improve it further.

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 'MCP server metadata' and enumerates three specific actions: health, capabilities, prompt_context, each with brief explanations. While distinct from siblings like 'get_system_summary', it doesn't explicitly differentiate itself, though the purpose is well-defined.

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 explicit guidance on when to use this tool versus siblings. The actions imply usage contexts (e.g., health for monitoring, prompt_context for AI priming), but there is no direct comparison or when-not-to-use advice, leaving the agent to infer.

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 must disclose behavioral traits. It states 'Read item data,' implying read-only, but does not specify safety, side effects, rate limits, pagination, or output structure. The lack of detail leaves agents uncertain about the tool's behavior beyond the basic operation.

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 sentence that efficiently front-loads the purpose ('Read item data') and enumerates actions. However, the dense list could be better structured (e.g., using bullet points) for readability.

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 (9 parameters, multiple actions) and lack of output schema, the description is incomplete. It does not explain how to use filters, what responses look like, or how actions interrelate, leaving significant gaps for an agent to use the tool effectively.

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 89% schema coverage, the input schema already provides most parameter descriptions. The description adds minimal extra meaning by grouping actions (e.g., 'all (list with optional filters)') but does not enrich parameter semantics beyond what the schema offers.

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 'Read item data' which is a specific verb+resource pair. It then lists the various actions, adding context for each (e.g., 'all (list with optional filters)'). However, it does not explicitly differentiate this tool from siblings like query_rules or query_things, which also have clear names but could cause confusion.

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 lists actions and their basic purpose but provides no guidance on when to use this tool versus alternatives. For example, it does not explain when to use query_items over query_rules or query_things, nor does it mention prerequisites or exclusions.

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

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

No annotations are provided, so the description must fully convey behavioral traits. It states 'Read' implying no side effects, but lacks details on permissions, return format, or any limitations. For a read tool, this is minimal but acceptable.

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 short sentences with no redundant information. Every word earns its place, making it highly concise 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 no output schema, no annotations, and two parameters (one optional), the description provides the essential purpose and usage. However, it lacks details about return values, error handling, or any prerequisites, making it minimally acceptable for a simple read 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 adds meaning to the 'action' parameter by explaining 'all (list all), get (by UID)', clarifying the enum values beyond the schema. The 'ruleUID' parameter is described as 'Used by: get', which is minimal but helpful. Schema coverage is 50%, and the description compensates somewhat.

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 'Read automation rules' and specifies two actions: list all or get by UID. This distinguishes from sibling tools like manage_rule, but could be more explicit about being read-only.

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 when to use each action parameter (all vs get), but does not provide guidance on when to choose this tool over siblings like manage_rule or automation. Implicit differentiation is not 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?

No annotations are provided, so the description carries full burden. It implies a read-only operation but omits details like pagination, rate limits, or what happens if the thingUID is invalid. Minimal behavioral disclosure beyond the basic read nature.

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) and front-loaded with the core purpose. Every word serves a purpose 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 lack of annotations and output schema, the description is too sparse. It does not explain return format, error behavior, or how results are structured. For a tool with two parameters and three actions, more context is 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?

With 50% schema description coverage, the baseline is 3. The description adds context by listing action values and their meanings (e.g., 'all (list all)'), but this mostly repeats the enum. The thingUID parameter is already described in the schema, so little extra 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 'Read thing data' and lists three actions, making the verb and resource explicit. However, it does not differentiate from the sibling 'query_items', which may cause confusion about which to use for item vs thing queries.

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 like 'manage_thing' or 'query_items'. There are no prerequisites, exclusions, or context for when to choose each action.

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 provided, and the description does not disclose whether operations are destructive or require specific permissions. It only hints at actions but lacks behavioral context like side effects or auth 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?

The description is concise and front-loaded with the purpose sentence, but the inline list of actions is somewhat cluttered. Still, no 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?

Given no output schema and no annotations, the description is insufficient. It does not explain return values, prerequisites, or side effects for a multi-action tool with 6 parameters.

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 high (83%), and the description adds minimal new information beyond the schema's 'Used by' notes. The action list is already in the enum.

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 lists multiple actions without a clear single-purpose verb+resource. 'Bulk remediation and generation' is vague and does not differentiate from sibling tools like manage_thing or execute_batch.

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 vs alternatives. There is no mention of when not to use it or which sibling tool to use instead for specific sub-actions.

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?

Describes the conversion process and return format (names, types, rooms, live states), but lacks explicit statement on side effects or read-only nature, though it is implied as a search 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?

Two sentences with no filler; first sentence states primary purpose, second provides usage instruction and examples. Efficient 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?

Complete for a single-parameter search tool; describes return value (ranked matches with attributes) compensating for lack of 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?

Gives concrete examples ('kitchen light') and explains the 'query' parameter expects natural-language intent, adding significant value beyond the schema's type definition.

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 is a 'PRIMARY item finder' that converts natural language into ranked matches with specific attributes, distinguishing it from sibling search tools like query_items.

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 explicit instruction to 'Call this BEFORE any other search', guiding agents on when to use it, though it does not list exclusions or 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?

The description discloses the delayed execution behavior, but lacks details such as whether the command runs once or repeatedly, if it can be canceled, or any side effects on the item. With no annotations, more transparency would be beneficial.

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 sentence with an example, containing no redundant words. It efficiently conveys the core functionality.

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 there are three required parameters and no output schema, the description is insufficient. It does not clarify what itemName refers to (the item to target? a name for the schedule?) or the expected format of command. The example is illustrative but not precise.

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 only 33% (only delayMs is described), but the description does not explain itemName or command parameters beyond the example. The example 'turn off in 20 minutes' implies parameter use but is vague about the exact string format.

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 'Schedule a command' and specifies the timing 'after a delay', with an illustrative example. It distinguishes from siblings like 'send_command' (immediate) and 'automation' (more complex scheduling).

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 clearly indicates the tool is for delayed command execution, but does not explicitly state when not to use it or mention alternative tools like 'send_command' for immediate execution.

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 only states behavior ('Send a command') but does not disclose side effects, authentication needs, rate limits, or whether the command is executed synchronously or asynchronously. The description is too brief 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 a single sentence, front-loading the action and target. It is efficient with no wasted words. However, brevity comes at the cost of completeness, which is acceptable given the tool's simplicity.

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

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

For a 2-param tool with no output schema and no annotations, the description covers the basic purpose and provides partial parameter hints. However, it lacks details on valid command syntax, item naming, or expected outcome, making it minimally adequate but not complete.

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

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

Schema coverage is 0% (no parameter descriptions in schema). The description adds meaning for 'command' by listing examples (ON, OFF, numeric value), but 'itemName' is left completely undefined. This is marginal improvement over raw schema but insufficient for full understanding.

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 ('Send a command') and the target ('to a single item'), specifying example command types (ON, OFF, numeric value). It implicitly distinguishes from sibling tools like 'execute_batch' (single vs batch) and 'schedule_command' (immediate vs scheduled), though not explicitly.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. There is no mention of valid items, command formats beyond examples, or contexts where this tool is appropriate.

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