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

No annotations are provided, so the description carries full burden. It lists actions but does not disclose whether operations are read-only or destructive, authorization requirements, rate limits, or side effects. For example, 'create_team' implies mutation but lacks safety context.

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

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

The description is well-structured: a brief summary of scope, a note on the action parameter, a clear table of actions, and examples. It is concise but comprehensive enough for the multi-action tool.

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

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

For a multi-action tool with no output schema, the description covers each action's purpose and parameter requirements with examples. It lacks return value details, but the examples partially compensate. Overall, it provides sufficient context for an agent to select and invoke the correct action.

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 100% description coverage, but the description adds substantial meaning: it specifies which actions require which parameters (e.g., 'list_teams needs area_id', 'create_team needs area_id + body') and provides examples. This goes beyond the bare 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 tool handles 'Account information, API usage, areas, and teams,' and lists specific actions (get_user, api_usage, list_areas, list_teams, create_team) with verbs. This distinguishes it from sibling tools focused on agents, devices, or alerts.

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 clear context that this tool is for account-level operations, with examples. However, it does not explicitly state when not to use it or mention alternative sibling tools for other domains, though the sibling list implies differentiation.

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?

As no annotations are present, the description fully covers behavioral traits: lightweight HEAD requests for count actions, the exception for list_uptime_all, pagination details, ISO 8601 defaults, and required parameters. It could add more on side effects of destructive actions like delete.

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 long but well-structured with clear sections (ACTION REFERENCE, GOTCHAS, EXAMPLES) and front-loaded purpose. Every part serves a purpose, though some redundancy exists.

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 (21 parameters, 31 actions) and lack of output schema, the description is thorough. It covers actions, parameters, and edge cases, but lacks return value details for many actions and examples for body 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?

With 100% schema coverage, the description goes far beyond by grouping parameters by action, explaining when they apply, providing gotchas and examples. This adds significant value for correct invocation.

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 resource ('Domotz collectors (agents)') and the purpose ('Manage'), and provides a comprehensive list of specific actions. It is distinct from sibling tools focused on other resource types.

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 (e.g., which require agent_id, which are lightweight HEAD requests) and provides filtering/pagination guidance. It does not explicitly contrast with sibling tools but the domain is clear.

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

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

Discloses workflow dependencies (list_profiles first), scope of get_device_bindings (all devices), and deprecation status. No annotations exist, so description carries full burden; it covers core behaviors but could mention mutation effects or idempotency.

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 with clear sections (action reference, gotchas, examples). Every sentence adds value; no redundancy. Front-loaded with purpose and action overview.

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

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

Covers all actions, parameters, gotchas, and examples. Lacks description of return values (no output schema), but for a management tool, examples provide sufficient guidance. Could benefit from stating what each action returns.

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

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

Schema has 100% coverage with parameter descriptions. The description adds critical context: which parameters are required for each action, the binding workflow, and the deprecation note, significantly aiding accurate invocation.

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: 'Manage alert profiles and their bindings to collectors and devices.' It then enumerates specific actions, which distinguishes it from sibling tools like domotz_agents or domotz_devices.

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

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

Provides explicit action reference with required parameters, gotchas (e.g., binding workflow, get_device_bindings behavior), and examples for common use cases. It also notes deprecation of list_profiles_deprecated, guiding the agent to prefer list_profiles.

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 fully covers behavioral traits: it lists all actions, required parameters, and body requirements. It discloses the backup workflow sequence and notes which actions need a body. However, it does not mention idempotency, 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 well-structured with sections: summary, action reference, gotchas, and examples. Every sentence adds value, and critical information is front-loaded. No wasted text.

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

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

Given the complexity (multiple actions, 5 params, no output schema), the description covers actions, parameters, workflow, and examples. It lacks explicit return value descriptions and error conditions, but the examples and action list are sufficient for basic usage.

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?

Input schema coverage is 100%, but the description adds meaning by specifying which actions require the 'body' parameter and that 'configuration_timestamp' is used for 'get_config'. Examples further illustrate parameter usage, going beyond pure schema documentation.

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

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

The description clearly states 'Manage device configuration backups, credentials, and SNMP authentication,' which specifies the scope. The action reference lists eight distinct operations, differentiating this tool from siblings like domotz_agents or domotz_monitoring.

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 'GOTCHAS' section explaining the backup workflow order and notes that agent_id and device_id are required for all actions. However, it does not explicitly compare to siblings or state when not to use this tool, so implicit usage context is strong but lacks 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?

With no annotations, the description fully carries the burden. It discloses that delete_down deletes ALL down devices, count_applications/count_variables use HEAD requests, from/to default to last 7 days, and edit uses a field URL parameter. These are critical behavioral 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?

The description is well-structured with sections: overview, ACTION REFERENCE, GOTCHAS, and EXAMPLES. It is somewhat lengthy but each section adds necessary context. Front-loading the purpose is effective.

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

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

Given the complexity (17 actions, 20 params, no output schema), the description covers actions, required parameters, gotchas, and examples well. It does not detail return values, but the action reference and examples provide sufficient context 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 100%, but the description adds significant value by explaining each action's usage, the meaning of the 'field' parameter for edit, and that from/to accept ISO 8601 timestamps. It goes beyond the schema's basic 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 'Manage devices on Domotz collectors' and lists all supported actions via the action parameter. It distinguishes this tool from sibling tools (e.g., domotz_agents, domotz_search_devices) by focusing on device-level operations.

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

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

The description provides an ACTION REFERENCE detailing which parameters are required for each action (e.g., 'list' needs agent_id, 'edit' needs field and body). It also includes a GOTCHAS section and examples. It does not explicitly contrast with sibling tools, but the scope is clear.

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

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

No annotations are provided, so the description carries the full burden. It details all eight actions and their required parameters, includes 'GOTCHAS' about workflow dependencies, and mentions the optional 'include_unrecoverable' flag. It does not describe side effects or permissions, but the action descriptions cover the main behavioral traits.

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

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

The description is well-structured into sections: summary, action reference (bulleted), gotchas, and examples. It is front-loaded with the purpose, each sentence adds value, and there is no redundancy. The format is easy to parse for an AI agent.

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

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

Given the complexity (8 actions, 8 parameters, no output schema), the description is comprehensive. It covers all actions, explains the workflow, and provides examples. It could mention the return format of each action, but the action reference and examples partially compensate. Overall, it is sufficiently complete for selecting and invoking the tool.

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

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

Schema coverage is 100%, so the schema already describes each parameter. However, the description adds significant value by grouping parameters per action (e.g., 'list needs no parameters', 'create_association needs custom_driver_id + agent_id + device_id + body'), which goes beyond the schema's flat property 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 'Manage custom drivers and their associations with devices', specifying the resource (custom drivers) and actions (list, get, create_association, etc.). It distinguishes from sibling tools (e.g., domotz_agents, domotz_devices) by focusing on driver-specific operations.

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

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

The description includes a 'GOTCHAS' section with workflow guidance (list drivers first, then create_association) and clarifies that execute_action needs action_id from the driver definition. It provides examples for list and list_associations. While it does not explicitly state when not to use this tool vs alternatives, the action reference and context make it clear.

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

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

With no annotations, the description describes key behaviors: combining multiple data types and summarizing the device list (first 50 + total count) when there are over 50 devices. It notes the agent_id requirement. It does not mention read-only status or potential performance implications, but covers the main behavioral traits.

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 4 sentences, front-loaded with the main purpose, then adds details on content, usage, requirement, and a specific limitation. Every sentence is valuable and there is no redundancy.

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

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

Given the tool's simplicity (one parameter, no output schema), the description provides a good overview of what is returned (agent details, device list, uptime) and a behavior limit (summary for >50 devices). It could mention if pagination is needed but is otherwise 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 already fully describes the single parameter agent_id with a description. The description reiterates the requirement but adds no new semantic information beyond what is in the schema, so it meets the baseline without adding 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 specifies the verb 'Get', the resource 'collector overview', and the scope 'single call' combining agent details, device list, and uptime. It distinguishes itself from sibling tools like domotz_get_device_full_status which targets a single device, and separate tools for agents and devices.

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

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

The description advises using this as a starting point when exploring a collector/site, providing clear context. It does not explicitly state when not to use or list alternatives, but the guidance is helpful.

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. It discloses that results are summarized if >50 items in any category and that it combines multiple API calls into one, indicating no destructive side effects. Could mention performance or error handling, but sufficient for safe invocation.

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

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

Four concise sentences: purpose, components, usage guidance, requirement and behavior note. Front-loaded with key phrase. No unnecessary words, each sentence adds value.

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

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

Given the simple parameters (agent_id, device_id) and no output schema, the description covers purpose, usage context, parameter requirement, and a behavioral note (summarization). Could mention error conditions or rate limits, but adequate for an AI agent to decide.

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

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

Schema coverage is 100%: both parameters have clear descriptions in the schema. The description merely restates 'Requires agent_id and device_id' without adding new semantics. Baseline 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's purpose: 'Get comprehensive device status in a single call' and specifies it combines 5 API calls (device info, status history, SNMP sensors, TCP sensors, alert bindings). This distinguishes it from sibling tools like domotz_get_agent_overview or domotz_search_devices.

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

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

The description provides clear usage guidance: 'Use this instead of making separate calls when you need a full picture of a device.' It implicitly contrasts with separate API calls but does not explicitly state when not to use it (e.g., if only one data type is needed).

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 burden. It mentions a caution for delete_inventory ('caution: removes all') and lists required parameters, but it does not disclose other behavioral traits like idempotency, side effects of each action, or authentication needs. More comprehensive disclosure would improve 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 well-structured with an action reference and examples. It front-loads the purpose in the first sentence. While lengthy due to 19 actions, every section serves a purpose. Minor redundancy in 'needs' statements could be trimmed, but overall efficient.

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

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

Given the tool's complexity (19 actions, 7 parameters) and no output schema, the description covers all actions, required parameters, and provides examples. It omits output details and error handling, but for a multi-action tool, it is fairly comprehensive.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond by detailing which parameters are needed for each action (e.g., 'create_field: needs inventory_field name + body'), adding context that the schema alone lacks. This significantly aids tool invocation.

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 'Manage inventory fields, custom tags, device profiles, and device types,' which specifies the resource and action. This differentiates from sibling tools like domotz_devices or domotz_alerts, which focus on other domains.

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 does not explicitly state when to use this tool versus alternatives. The purpose is implied through the name and first sentence, but no direct comparison or exclusion criteria are provided. The sibling tools have distinct focuses, but guidance on switching between them is absent.

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 fully discloses behavioral traits: it specifies that sensor_id vs service_id are sensor-type-specific, trigger creation depends on valid function_id, and timeseries parameters default to last 7 days. It also warns about the exact error handling expectations ('If ANY step returns an error, STOP and report').

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 lengthy but well-structured with labeled sections (ACTION REFERENCE, TRIGGER WORKFLOW, GOTCHAS, EXAMPLES). It is front-loaded with the purpose and a key note about required parameters. While some redundancy exists (repeated requirement for agent_id and device_id in examples), the structure justifies the length given the tool's complexity.

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 high complexity (10 parameters, 13 actions, no output schema), the description covers most critical aspects: parameter usage per action, workflow order, error handling, and credential reqs. Minor gap: it does not describe return values or response structure, which a monitoring tool might rely on, but the examples and references mitigate this.

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

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

Despite 100% schema description coverage, the description adds substantial meaning: it explains the 'action' enum values with context (e.g., 'list_snmp: List all SNMP sensors on a device'), clarifies parameter dependencies (e.g., 'sensor_id' needed for SNMP actions, 'service_id' for TCP), and describes the 'body' object structure (OID config, port/host, function_id, etc.) beyond the schema's generic 'Request body'.

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 'Manage SNMP and TCP sensors (called Eyes in Domotz) on devices.' This verb+resource combination precisely defines the tool's scope, distinguishing it from siblings like domotz_agents or domotz_devices which handle other aspects.

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 an ACTION REFERENCE detailing 13 specific operations with their required parameters, a TRIGGER WORKFLOW with step-by-step instructions including error handling, and GOTCHAS that clarify when not to use certain actions (e.g., TCP sensors do not support triggers). This offers explicit 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 bears full burden. It does not disclose whether actions are destructive, reversible, or require special permissions. While it lists actions like delete/set, it offers no warnings about their effects.

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

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

The description is well-organized into an introductory line, an action reference, and examples. It efficiently conveys necessary information without redundancy, though the action list is somewhat lengthy.

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 no output schema, so return values are undefined. The description covers operations and parameters adequately for a configuration tool, but lacks details on pagination, error handling, or rate limits.

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

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

Schema coverage is 100% and describes basic parameter types. The description adds value by mapping each action to required parameters (e.g., body for set/create, device_id for excluded) and providing concrete usage 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 it manages network scan policies, interfaces, routed networks, and excluded devices. It enumerates 14 specific actions and provides examples, making the tool's purpose distinct from sibling tools like domotz_agents or domotz_devices.

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

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

It explicitly requires agent_id for all actions and links actions to required parameters (e.g., device_id for excluded devices). Examples demonstrate correct usage. However, it does not explicitly state when to avoid this tool in favor of 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?

With no annotations provided, the description fully covers behavioral aspects. It explains the purpose and prerequisites of each action, parameter usage, and potential pitfalls (e.g., 'field' param for power_action). The examples illustrate exact usage patterns.

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

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

The description is well-structured with clear sections (ACTION REFERENCE, GOTCHAS, EXAMPLES). It is comprehensive yet concise, with every sentence adding value. The examples are minimal and illustrative.

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, multiple actions, nested objects) and absence of an output schema, the description is remarkably complete. It covers all actions, parameter relationships, required fields per action, and common workflows.

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?

Though input schema coverage is 100%, the description adds significant meaning beyond schema definitions. It explains the enum values for 'action', the purpose of 'field', 'outlet_action', and provides context for conditional parameters like 'attached_device_id'. The structured reference and examples clarify 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 the tool manages device power actions and PDU power outlets. It enumerates all specific actions (get_power_actions, power_action, etc.) and differentiates from sibling tools like domotz_agents and domotz_devices which cover different domains.

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 advice for each action, including workflow guidance (e.g., call get_power_actions before power_action) and gotchas about parameter naming (outlet_action vs action). It also includes examples for several 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 provided, so the description carries full burden. It discloses the search scope (one or all collectors) and that results include agent_id. Missing information on pagination, result limits, or performance implications, but sufficient for basic usage understanding.

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 purpose is front-loaded in the first sentence, making it immediately clear what the tool does.

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 search tool without output schema, the description explains key aspects: search scope, return field (agent_id), and parameter behavior. It lacks details on error handling or result count limits, but covers the main use case adequately.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds minimal value beyond the schema, explaining the effect of omitting agent_id. Baseline 3 is appropriate as schema already handles semantic explanation.

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 searches devices by name or IP across one or all collectors, with a specific verb-resource combination. It distinguishes from siblings like domotz_devices (list all) or domotz_get_device_full_status (detail view).

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: provide a query and optionally an agent_id to limit scope. It also notes that omitting agent_id searches all collectors, making it great for cross-site device discovery. However, it does not explicitly mention when not to use or contrast with sibling tools.

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