UniFi MCP Server

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

With no annotations, the description carries the full burden, and it does disclose the mutation gate: confirm must be true to apply, and dry_run previews without applying. That is genuinely useful behavioral context, but it omits permission requirements, reversibility, and what a preview actually returns.

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

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

The purpose sentence is front-loaded and efficient, but the Args/Returns docstring block is boilerplate and the Returns line restates what the output schema already provides. It is adequately sized but not tightened.

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 5-parameter mutation tool with no annotations, this covers the core operation and the confirm/dry_run gate, and the output schema handles return values. The missing 'controller' semantics and the phantom 'settings' entry leave the definition incomplete for correct invocation.

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 20%, so the description must compensate, and it documents subscriber_id, plan_id, confirm, and dry_run (including the required-unless-dry_run rule). However it introduces a 'settings' parameter that does not exist in the schema and never mentions the real 'controller' parameter, leaving one parameter fully undocumented.

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

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

The first line states a specific verb and resource: assigning a service plan to a UniFi Carrier Fabric subscriber. It is clear what the tool does, though it does not distinguish itself from the nearby update_carrier_subscriber sibling, so an agent could confuse the two.

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 update_carrier_subscriber, create_carrier_subscriber, or the plan-listing tools. The dry_run/confirm mechanics imply a preview-then-apply workflow but the description never states it as usage guidance or names alternatives.

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

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

With no annotations, the description carries the full behavioral burden; it discloses that confirm must be true to apply and dry_run previews without applying, which are valuable invocation-safety traits. However, it omits authentication requirements, reversibility, side effects on existing attachments, and error behavior, so the disclosure is partial.

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

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

The purpose is front-loaded and the Args/Returns block is cleanly structured, with no rambling. However, the Returns line is redundant with the output schema and the phantom 'settings' argument is wasted text, slightly reducing efficiency.

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

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

For a mutation tool with no annotations and only 20% schema coverage, the description explains the attach action and the confirm/dry_run contract. It still leaves gaps around permissions, failure modes, and the relationship to detach_carrier_subscriber_host, so it is not fully complete for an agent to invoke safely.

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 20% (only controller is documented in the schema), so the description must compensate. It adds meaningful confirm/dry_run rules and marks host_id as required, but subscriber_id/host_id definitions are tautological, controller is left to the schema, and 'settings' is mentioned despite not existing in the schema, creating confusion.

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 opening sentence names a specific verb ('Attach'), resource ('gateway host'), and target ('UniFi Carrier Fabric subscriber'), making the operation unambiguous. It does not explicitly contrast with the sibling detach_carrier_subscriber_host or state exclusions, so sibling differentiation is implicit rather than stated.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as detach_carrier_subscriber_host or update_carrier_subscriber. The only usage cue is the implied purpose of attaching a host, leaving the agent to infer when 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.

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the analyzed metrics but says nothing about the read-only nature, permissions/controller scoping, rate limits, or cost — a significant gap for a no-annotation 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 first sentence is front-loaded and clear, but the boilerplate Args/Returns block is partly wasted and partly wrong — it documents a nonexistent 'settings' argument and restates return values already covered by the output schema.

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?

An output schema exists, so return values need not be explained, and the metric list gives reasonable coverage of what the tool does. The stale 'settings' argument and the absence of any scoping or permission context leave it only minimally 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 100% and the controller parameter is well documented in the schema itself, so the baseline would be 3. However, the description's 'Args: settings: Application settings' refers to a parameter that does not exist in the schema, which is actively misleading and worth a deduction.

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 uses a specific verb+resource ('Compare performance metrics across all sites') and enumerates the metrics analyzed (uptime, latency, bandwidth, health status), so an agent knows what it returns. It does not, however, explicitly distinguish itself from close siblings like get_cross_site_statistics or get_site_health_summary, which appear to overlap heavily.

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

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

There is no when-to-use guidance and no exclusion or alternative mentioned. With many sibling tools operating on the same site/health data, the description leaves the agent to infer when cross-site comparison is preferred over per-site health or statistics endpoints.

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 add useful behavioral context: 'confirm' must be True to execute and 'dry_run' previews without sending. However, it doesn't disclose the destructive nature of DELETE, authentication requirements, rate limits, or what happens on failure.

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 front-loaded with the core action and uses a structured Args/Returns format. It's appropriately sized with no wasted sentences, though the Args section could be slightly more informative.

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 is a destructive DELETE operation with 5 parameters, no annotations, and only 20% schema coverage, the description is functional but incomplete. It doesn't explain the destructive implications, safety requirements, or the controller parameter. However, the output schema exists, so return values needn't be fully explained.

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 only 20% description coverage, so the description must compensate. The Args section covers 5 parameters including 'console_id' and 'path', but the 'controller' parameter is documented only in the schema, not the description. The description adds meaning for most parameters but misses one.

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

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

States a specific verb+resource: a DELETE request proxied to the Network Application via Cloud Connector. This clearly distinguishes it from siblings like connector_network_post/put/patch/get, so it earns a 4 rather than a 3.

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 or when not to use it. The 'confirm' and 'dry_run' semantics are listed in Args but the description never explains when a caller should use dry_run.

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 and it does disclose meaningful behavior: the request is forwarded to a specific upstream URL, the raw unprocessed response is returned, and it documents two failure modes (ValidationError on empty inputs, ValueError when Site Manager API is disabled). It omits auth requirements, rate limits, and idempotency, but covers prerequisites and errors better than most.

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 docstring-style Args/Returns/Raises layout is front-loaded with the core operation and endpoint before listing details. It is appropriately sized with little padding, though the Returns section partially duplicates what the output schema already provides.

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 passthrough proxy tool with an output schema present, the description covers the operation, endpoint, required inputs, and error conditions adequately. The main gap is the absent 'controller' parameter and the phantom 'settings' entry, plus no explicit read-only safety statement given the lack of annotations.

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 25%, so the description is expected to compensate. It documents path (with example sub-path), console_id (with sourcing hint), and params, adding real value the schema lacks — but it also lists a 'settings' argument that does not exist in the input schema, while the actual 'controller' parameter goes unmentioned, creating a discrepancy that could mislead an agent.

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

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

States a specific verb (proxy a GET request) and resource (Network Application via Cloud Connector), even giving the exact upstream URL template. The verb+resource combination clearly distinguishes it from the sibling connector_network_post/put/patch/delete 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?

It points the agent to list_hosts for console_id and gives a concrete path example, which is useful context. However, it never states when to choose this tool over connector_network_post/put/patch or the list_integration_* alternatives, leaving selection to inference from the HTTP verb.

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 and does disclose two genuinely useful traits: confirm must be True to execute, and dry_run previews without sending. However, it says nothing about what state PATCH mutates or destroys, whether it is reversible, what permissions are required, or how errors surface, leaving significant behavioral gaps for a write-class proxy.

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 one-line purpose is front-loaded and the Args/Returns structure is easy to scan. But the arg list restates schema fields and includes a phantom 'settings' entry, so the wrapping is not purely additive.

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?

An output schema exists, so return details are optional and adequately covered. But for a mutation proxy with zero annotations, the description omits the 'controller' parameter and invents a 'settings' parameter, and gives no when-to-use context against the sibling network-method tools, leaving an agent under-equipped to call it 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 only 17%, so the description should compensate, and it partially does by labeling console_id, path, and body. But it introduces a 'settings: Application settings' parameter that does not exist in the schema at all (misleading), while omitting the documented 'controller' parameter entirely. The mismatch actively harms 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?

States a specific verb and resource: it proxies a PATCH request to the Network Application via Cloud Connector. This clearly separates it from the sibling HTTP-method variants (connector_network_post, _put, _delete, _get), though the differentiation comes largely from the method word rather than an explicit comparison to those 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?

There is no guidance on when to use PATCH versus the sibling connector_network_put/post/delete tools, nor on required scoping or preconditions. The only usage-adjacent detail is the confirm/dry_run convention, which is behavioral rather than a selection criterion. An agent must infer when 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.

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the confirm gate for a mutating operation, the dry_run preview mode, the return shape ('raw response or dry-run preview'), and the two failure conditions (ValidationError, ValueError when Site Manager API is disabled). It stops short of permissions, idempotency, or rate-limit behavior, so not a 5.

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

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

Front-loaded with a single clear purpose sentence, then structured Args/Returns/Raises sections that are easy to scan. Slightly verbose docstring formatting, but each line carries information.

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

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

An output schema exists so return values needn't be explained, and the description covers the mutating nature, preview path, error conditions, and most parameters. The phantom 'settings' parameter and missing contrast with PUT/PATCH siblings are the remaining gaps.

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

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

Schema coverage is only 17%, so the description must compensate, and it largely does by explaining console_id provenance (from list_hosts), a path example, confirm semantics, and dry_run. However, it documents a 'settings' parameter that does not exist in the schema while omitting the schema's controller parameter, creating a real inconsistency that undermines the added 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?

States a specific verb+resource: proxying a POST request to the Network Application via Cloud Connector. This clearly distinguishes it from the sibling connector_network_get/put/patch/delete tools by HTTP semantics.

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

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

Usage is implied by the HTTP verb (POST for creating/submitting) and it notes confirm must be True to execute plus a dry_run preview option. However, it never explicitly contrasts this tool with connector_network_put or the other connector siblings, leaving the agent to infer the choice.

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 disclose the important safety mechanism ('confirm: Must be True to execute') and the dry_run preview, which is genuinely useful for a mutation tool, but it says nothing about permissions, what state the PUT overwrites, or error 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 Args/Returns structure is readable, but the parameter list largely restates schema keys and includes a phantom 'settings' entry, so several lines do not earn their place. Front-loading the one-line purpose is good.

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 six-parameter mutation tool with no annotations and only 17% schema coverage, the description is too thin. The existing output schema means return values need not be explained, but missing information about overwrite semantics, permissions, and the correct parameter set leaves gaps an agent must guess at.

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 only 17%, so the description must compensate, and it only does so superficially with one-line name glosses. Worse, the Args list includes a 'settings' parameter that does not exist in the schema while omitting the documented 'controller' parameter, reducing trust in the parameter 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 states a specific verb and resource: proxying a PUT request to the Network Application via Cloud Connector. The HTTP method distinguishes it from the sibling connector_network_get/post/patch/delete tools, though it does not explicitly name them.

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 PUT versus connector_network_patch or connector_network_post, nor any mention of prerequisites. The only contextual rule given is the confirm gate, which is behavioral rather than a usage-routing statement.

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 usefully discloses the confirm-gate ('Must be True to execute') and dry-run behavior ('Preview without sending'), which are important safety traits for a destructive DELETE proxy. However, it does not describe permissions, reversibility, or the consequences of deletion.

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 Args/Returns structure is front-loaded and compact. However, the 'settings: Application settings' line refers to a non-existent parameter, so it does not earn its place and introduces confusion.

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?

An output schema exists, so return-value explanation is optional, and the confirm/dry_run mechanics are covered. But for a destructive, unannotated DELETE proxy with low schema coverage, the description should explain when to use it versus sibling method-specific tools and should not leave a phantom parameter unexplained.

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 only 20%, so the description must compensate. It adds useful meaning for console_id, path, confirm, and dry_run, but it lists a 'settings' argument that does not exist in the schema (additionalProperties: false) and omits the controller parameter entirely. This mismatch actively misleads an agent about the tool's inputs.

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

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

States a specific verb (DELETE proxy) and resource (Protect Application via Cloud Connector), which distinguishes it from sibling connector_protect_get/post/put/patch tools by HTTP method. It does not explicitly name those siblings, so it falls short of the 5-level sibling differentiation standard.

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 no guidance on when to choose this over sibling tools like connector_protect_patch or connector_protect_put, nor any prerequisites such as permissions or required controller selection. The confirm/dry_run notes hint at execution mechanics but not usage context 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?

With no annotations, the description carries the burden and does well: it discloses the enablement prerequisite (Site Manager API required), the exact upstream URL, that the raw response is returned, and two named failure modes (ValidationError on empty console_id/path, ValueError when Site Manager is disabled). It omits read-only confirmation, rate limits, and pagination 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?

Purpose and target URL are front-loaded, followed by cleanly separated Args/Returns/Raises sections. Slightly verbose in the URL restatement but every block 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?

An output schema exists, so return-value detail is not required, and the description still characterizes the response as raw upstream output. For a proxy tool it covers prerequisites and errors adequately, missing only pagination/limits and the param-list discrepancy noted above.

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 only 25% (just 'controller'), so the description must compensate and largely does: console_id (from list_hosts), path (e.g. 'v1/cameras'), params (optional query params). However, it documents a 'settings' argument that does not exist in the schema while never addressing the schema's 'controller' parameter, creating a mismatch that could confuse an agent.

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

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

States a specific verb and resource ('Proxy a GET request to the Protect Application via Cloud Connector') and pins the exact target URL, so it is clearly distinct from connector_protect_post/put/patch/delete and connector_network_get. It never names a sibling explicitly, but the HTTP-method framing makes the family separation 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 explicit when-to-use or when-not-to-use guidance against the sibling connector_* tools. It does imply workflow context by noting console_id comes 'from list_hosts' and that UNIFI_SITE_MANAGER_ENABLED is required, which is useful but falls short of routing 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?

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: 'confirm: Must be True to execute' and 'dry_run: Preview without sending'. However, for a mutation (PATCH) it says nothing about required permissions, reversibility, or which settings are affected, so the disclosure is partial.

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 compact and front-loaded: the core action leads, followed by a short args list and return note. The only waste is the phantom 'settings' entry, which is a correctness issue rather than bloat.

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?

An output schema exists, so the brief return note is acceptable. But for an unannotated mutation proxy with 6 params at 17% coverage, the description should say more about prerequisites and effect; the non-existent 'settings' param and the unmentioned 'controller' param leave the agent under-informed.

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 only 17%, so the description must compensate and largely attempts to. It adds real meaning for confirm and dry_run ('Must be True to execute', 'Preview without sending'), but it lists a 'settings' parameter that does not exist in the schema and omits the schema's 'controller' parameter, creating a mismatch that undermines the added 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?

States a specific verb and resource ('Proxy a PATCH request to the Protect Application via Cloud Connector'), which clearly identifies it as the PATCH variant among the connector_protect_get/post/put/delete siblings. It does not, however, explicitly name which sibling to use under which condition, leaving differentiation to the HTTP-method convention.

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 explicit when-to-use or when-not-to-use guidance, and no routing to alternatives such as connector_protect_put or connector_protect_post. The only contextual hint is the confirm/dry_run gating, which governs execution but not tool selection.

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, and it partially delivers by disclosing the confirm-to-execute safety gate and the dry_run preview mode. It omits what the POST actually does (creates vs modifies), required permissions, and side effects, so the behavioral profile is only partly 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?

Docstring-style and front-loaded: the purpose sentence comes first, followed by terse per-argument lines and a return note. Reasonably tight with minimal waste, though the argument list is somewhat bare rather than explanatory.

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?

An output schema exists, so 'Raw response or dry-run preview' is sufficient for returns. But for a 6-parameter, no-annotation write operation the description leaves gaps: no auth prerequisites, no statement of what the POST mutates, and the controller routing parameter is undocumented.

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 low (17%), so the description must compensate; it annotates most params (console_id, path with format example, body, confirm, dry_run). However it introduces a 'settings' argument absent from the schema and omits the 'controller' parameter entirely, so it neither fully covers nor cleanly matches 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?

States a specific verb and resource: proxying a POST request to the Protect Application via Cloud Connector. The HTTP method plus target distinguishes it from sibling connectors (connector_protect_get/patch/put/delete), though it never names them 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?

There is no explicit when-to-use guidance or comparison to the other connector_protect_* verbs. The path example ('v1/cameras/{id}/snapshot') implies a usage context, and 'confirm must be True' implies a gate, but the agent gets no criteria for choosing POST over PUT/PATCH.

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, and it does disclose two important behavioral traits not present in the schema: a mandatory confirm gate before execution and a dry_run preview mode. It still omits what the mutation targets, whether PUT is idempotent here, and any auth/scope 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?

Front-loaded with a single clear sentence followed by a compact Args block and a Returns line. No filler or repetition. The Args list carries its weight, though the stray 'settings' entry is noise that dilutes it slightly.

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

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

An output schema exists, so the Returns line is adequate and return values need not be explained. For a mutating, no-annotation tool with only 17% schema coverage, the description is roughly adequate but leaves gaps: what happens if confirm is omitted, whether dry_run still validates, and the controller parameter's role beyond the schema note.

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 only 17% (just 'controller'), so the description must compensate, and it partially does via the Args list for console_id, path, body, confirm, dry_run. However it lists a 'settings' parameter that does not exist in the schema and never mentions 'controller', which is a real semantic mismatch that could mislead an agent.

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

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

States a specific verb and resource: 'Proxy a PUT request to the Protect Application via Cloud Connector.' The HTTP method plus target application is concrete and matches the tool name. It does not, however, differentiate itself from the closely named siblings connector_protect_post and connector_protect_patch, so an agent must infer the distinction from the method alone.

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?

Useful invocation guidance is embedded in the arg notes: 'confirm: Must be True to execute' and 'dry_run: Preview without sending.' But there is no guidance on when to choose PUT over the sibling connector_protect_patch or connector_protect_post, nor any stated prerequisites. Usage is implied rather than routed.

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 disclose the safety mechanism (dry_run preview vs confirm to apply) and the return value, which is genuine behavioral context. However, it omits permissions/auth needs, idempotency behavior, what happens on conflicting subscriber_number, and side effects of plan_id/host_id assignment.

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?

Purpose statement is front-loaded, then a scannable Args block, then Returns. No filler sentences. The list is somewhat mechanical and repeats schema field names, but it earns most of its length through the added constraints.

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 an output schema present, the description need not explain return structure, and it correctly just says it returns the created subscriber. It covers params and the confirm/dry_run gate well. Remaining gap: no discussion of how plan_id/host_id interact with the dedicated assign/attach sibling tools, and the stray 'settings' arg is unexplained.

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 only 9% (effectively just controller), so the description must compensate and largely does: it glosses all ten user-facing fields and adds constraints not in the schema, e.g. subscriber_number is '1-32 characters, required'. It even lists 'settings' which is absent from the schema properties, a minor inconsistency, and does not mention controller (left to 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?

Opens with a specific verb+resource: 'Create a UniFi Carrier Fabric subscriber.' An agent immediately knows the operation and domain. It does not differentiate from siblings like update_carrier_subscriber, suspend_carrier_subscriber, or attach_carrier_subscriber_host, so it stops short of a 5.

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 explicit when-to-use/when-not section or alternative routing, but the confirm/dry_run annotations ('Must be true to apply the change (required unless dry_run)', 'Preview the change without applying it') implicitly describe the intended mutation workflow. Useful but not a substitute for real usage guidance.

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

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

With no annotations, the description carries full burden, and it does disclose the safety gates: confirm must be true to apply, dry_run previews without applying. However, it says nothing about irreversibility, required permissions, or the effect on an in-progress service, which matters for a mutating detach 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 purpose is front-loaded in the first sentence, followed by a compact Args block and a Returns line. Slightly padded by the Returns line, which duplicates the existing output schema, but overall tight and well-ordered.

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?

An output schema exists, so the Returns line is redundant rather than necessary. For a mutation tool with no annotations, the description covers the dry_run/confirm safety model but leaves out reversibility, preconditions, and corrects neither the phantom 'settings' param nor the missing controller coverage.

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 25% (just controller is documented in-schema), so the description must compensate. It documents subscriber_id, confirm, and dry_run, but it lists a 'settings' parameter that does not exist in the schema while omitting the controller parameter — a misleading phantom argument alongside a real gap.

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

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

States a specific verb and resource ('Detach the gateway host from a UniFi Carrier Fabric subscriber'), which clearly identifies the operation and distinguishes it from the inverse sibling attach_carrier_subscriber_host. It stops short of explicitly naming that sibling, so routing to detach vs attach still relies on the verb.

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 detach instead of attach, what precondition (a currently-attached host) must hold, or what happens if no host is attached. The only usage-like content is the inline note that confirm is required unless dry_run, which is a within-tool rule rather than when-to-use vs alternatives.

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

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

No annotations are provided, so the description carries the full burden. It does disclose a meaningful behavioral trait — it raises ValueError when the cloud API is disabled or any identifier is empty — but says nothing about permissions, reversibility (implied read-only), or the download result beyond noting an output schema exists.

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 docstring-style Args/Raises layout is reasonably front-loaded and mostly informative, but the 'settings: Application settings' line is wasted space referring to a parameter that does not exist, and the heavy reST backticks add noise for no semantic gain.

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?

An output schema exists so return values need not be explained, and error behavior is covered. However, with 4 parameters at 25% schema coverage and one argument misnamed, the definition is only marginally complete for an agent to invoke it confidently.

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 25% (only 'controller' is described), so the description must compensate. It documents console_id, plan_id, and filename with sources, which is helpful, but it lists a phantom 'settings' argument that is not in the schema and leaves the real 'controller' parameter unaddressed, creating confusion.

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

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

States a specific verb and resource: 'Download an asset (e.g. floor plan image) from InnerSpace.' An agent can identify it as a read/download operation on InnerSpace assets. Sibling differentiation is only implicit (no other download tool, but no explicit routing to list_innerspace_floor_plans).

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

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

Usage is implied rather than stated. The Args block hints at the prerequisite source for console_id ('from list_hosts'), which is a useful dependency signal, but there is no explicit when-to-use/when-not or alternative-tool 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?

With no annotations, the description carries the behavioral burden and does disclose the return semantics: controller name, source ('session' from select_controller vs 'default'), and that both are None when neither is set. It does not explicitly declare the read-only/no-side-effect nature or any auth/rate-limit constraints, but for a zero-param getter this is reasonably transparent.

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, front-loaded with purpose before the Returns block. No redundant or filler content; the return-source detail is useful and compact.

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 (no params) and the presence of an output schema, the description supplies enough purpose and behavior for correct invocation. It leaves out usage-guidance details, but those are covered under usage_guidelines rather than 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?

The tool takes zero parameters, so there is no parameter semantics to document. Per the calibration rule, a 0-param tool with high schema coverage has a baseline of 4.

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

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

States a specific verb ('Show') and resource ('which controller a tool call without ``controller`` would target'), and names select_controller as the source for session-scoped controllers, distinguishing it from list_controllers and select_controller. An agent can tell it apart from siblings without opening schemas.

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 no explicit when-to-use guidance or exclusions. It does not tell the agent when to prefer this over list_controllers or select_controller, nor does it state prerequisites such as needing an active session. Usage is only inferable from the purpose statement.

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 behavioral burden. 'Get' implies a read, but the description says nothing about required permissions, error behavior for unknown IDs, or controller-selection side effects, and an output schema already covers return shape.

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 opening sentence is front-loaded and efficient, but the Args/Returns scaffolding adds an argument ('settings') that the tool does not accept, so a sentence that should earn its place instead introduces noise.

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?

Because an output schema exists, the Returns line is redundant rather than missing. The core gap is the undocumented relationship to the controller parameter (only covered by the schema) and the phantom 'settings' arg, leaving the definition adequate but not fully trustworthy.

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 Args block documents plan_id, but schema coverage is only 50% and the documented 'settings: Application settings' does not exist in the input schema, which lists plan_id and controller. This stale/mismatched argument list actively misleads rather than adding meaning.

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

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

States a specific verb (Get), resource (UniFi Carrier Fabric service plan) and scope (by ID), which cleanly separates it from the sibling list_carrier_service_plans. It stops short of naming that sibling explicitly, but the singular 'by ID' framing makes the distinction inferable.

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 list_carrier_service_plans or any other sibling, no prerequisites, and no mention of what happens if the plan_id does not exist. The agent is left to infer usage entirely from the name.

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 behavioral burden. It implies a read ('Get') but discloses nothing about permissions, error behavior for unknown IDs, or rate limits; 'Returns: The subscriber as a dictionary' is the only behavioral hint and is vague.

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

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

Front-loaded with purpose in one sentence, then compact Args/Returns blocks. The only waste is the phantom 'settings' line, but overall it is tight and well-ordered.

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?

An output schema exists, so the return value needn't be explained. However, for a tool with no annotations the description omits all behavioral context and misstates the parameter set, leaving it only minimally 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 50%: subscriber_id has no schema description and controller is documented in the schema, not the description. The description's 'subscriber_id: Subscriber identifier' adds nothing, and it introduces a 'settings' parameter that does not exist in the schema, which is actively misleading.

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

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

States a specific verb+resource and a lookup key ('Get a UniFi Carrier Fabric subscriber by ID'), which cleanly distinguishes it from list_carrier_subscribers and create/update siblings. It does not explicitly name those alternatives, but the 'by ID' scope is unambiguous.

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

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

No when-to-use guidance, no conditions or prerequisites, and no alternatives named (e.g. list_carrier_subscribers for enumeration). The agent must infer the read-by-ID use case entirely from the name.

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 behavioral burden, and it discloses almost nothing: no auth requirements, no scope of aggregation (which sites are included?), no rate limits, no indication of cost or latency. The "Returns" line merely restates the opening sentence and is redundant with the output schema.

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 text is short, but the Args/Returns scaffolding is boilerplate that adds no information: "Returns: Cross-site statistics" duplicates the first sentence verbatim in meaning. Front-loading is fine, but the body does not earn its place.

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

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

For a cross-site analytics tool with no annotations, the description should at minimum explain what is aggregated, which sites are covered, and how the controller argument affects scope. Instead it supplies a misnamed argument and a circular return statement. The output schema covers the shape of the response, so the missing behavioral context is the real deficiency.

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 documents an argument named "settings," but the schema's only parameter is "controller" — the description actively misnames and mischaracterizes the parameter. Although schema coverage is 100% (which would normally justify a baseline of 3), the description adds incorrect information rather than reinforcement, and the useful default-resolution behavior described in the schema is not echoed or clarified.

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

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

States a specific verb and resource ("Get aggregate statistics across multiple sites"), which is clearer than a tautology. However, it offers no differentiation from nearby siblings such as compare_site_performance, get_site_health_summary, or get_site_inventory, all of which also return cross-site or aggregate data. An agent cannot tell from this line why it should pick this tool over those.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives. With siblings like compare_site_performance and get_site_health_summary in the same family, the absence of routing guidance is a real gap.

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 behavioral burden, and it discloses almost nothing: no authorization requirements, no error behavior for a missing/invalid host, and no note that the result is scoped to the selected controller. For an unannotated tool this is a significant gap.

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-loads the essential purpose in one sentence, which is good. But the docstring Args/Returns boilerplate contributes little, and one of its arg entries ('settings') is not a real parameter, so the structure is not entirely trustworthy.

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?

An output schema exists, so the terse 'Returns: Host details' is acceptable. But with no annotations and a phantom 'settings' parameter reference, the description does not supply enough context for correct invocation relative to its siblings.

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

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

Schema description coverage is only 50%: 'controller' is well documented in the schema, but 'host_id' has no schema description, and the description's 'Host identifier' is a tautology that adds nothing. Worse, the Args block lists a 'settings' parameter that does not exist in the schema (additionalProperties: false), which could mislead the agent.

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

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

States a specific verb and resource ('Get host details by ID'), so the agent knows exactly what it returns. However, it makes no attempt to distinguish itself from the sibling 'list_hosts', so the retrieval-singular vs. list-plural choice is left to inference.

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 versus 'list_hosts', when an ID is already known, or what happens if the ID is unknown. The only usage hint present ('see list_controllers', 'select_controller') lives in the schema, not the description.

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, and it does add something concrete: it raises ValueError when the cloud API is not enabled or console_id is empty, which signals a prerequisite (cloud API must be on) and an error mode. It still omits auth requirements, whether this is purely read-only, and anything about the controller selection behavior that the schema hints at.

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

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

The purpose line is front-loaded and the Args/Raises layout is scannable with no padding sentences. It loses a point because one of the three lines (the phantom 'settings' arg) is wasted and actively misleading rather than earning its place.

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

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

An output schema exists, so return values need no explanation, and for a two-parameter read tool this is close to adequate. But the description leaves the core question — what 'project data' contains — unanswered, omits the controller parameter entirely, and cites a parameter that isn't in the schema, so an agent cannot fully predict its behavior.

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 50% (controller documented, console_id not), so the description must compensate. It usefully documents console_id's origin in list_hosts, but it never mentions the controller parameter, which materially changes which controller is queried, and it documents a 'settings' argument that does not exist in the schema — a stale, misleading entry.

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

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

The description states a verb and resource ('Get the InnerSpace project data') scoped to 'the integration on a console', which is better than a tautology. However, 'project data' is opaque — it does not say what is actually returned or how this tool differs from siblings like list_innerspace_floor_plans, list_innerspace_access_points, or list_innerspace_inventory, all of which live in the same domain.

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 only routing hint is provenance for one argument ('console_id ... from list_hosts'). There is no statement of when to use this tool versus any of the many other InnerSpace/integration list and get tools, and no prerequisites beyond the raised error.

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 behavioral burden, yet it only says it fetches a client. Nothing about auth/permissions, error behavior when the client is absent, connectivity requirements, or rate limits is disclosed. The read nature is implied but not enriched.

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

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

Front-loaded purpose is good and the entry is short, but the docstring-style Args block spends lines restating parameter names and includes a phantom parameter, so not every sentence earns its place.

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

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

An output schema exists, so return values need not be detailed. For a simple get-and-one tool this is largely adequate, but the phantom 'settings' parameter creates a real mismatch with the schema and lowers 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 only 33%, and the description's Args block merely restates site_id/client_id ('Site identifier', 'Client UUID') while introducing a 'settings: Application settings' parameter that does not exist in the schema. Meanwhile the 'controller' parameter — the only one whose defaulting behavior genuinely needs explanation — is left to 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 states a specific verb and resource ('Get a single connected client') and the word 'single' implicitly contrasts with the list_integration_clients sibling. It is clear but never names the alternative or otherwise differentiates 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?

There is no guidance on when to use this tool versus list_integration_clients or the other get_integration_* siblings. No prerequisites or context for selecting a single-client fetch are stated.

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 behavioral burden. 'Get' implies a read, but the description says nothing about permissions, whether the device must already be adopted, or behavior when the device is absent. For a no-annotation tool this is a meaningful gap.

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 prose is short and front-loaded in the first sentence, but the Args/Returns block is boilerplate that mostly restates schema fields, and it includes a stale 'settings' entry. Size is acceptable but the content does not fully earn its place.

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

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

An output schema exists, so return values ('Device details') need not be elaborated. However, with no annotations, 33% schema coverage, and an incorrect parameter list, the description is not fully complete for correct invocation.

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 only 33% and the docstring's parameter list is inaccurate: it lists 'settings: Application settings', which does not exist in the schema (the third parameter is 'controller'). Only site_id and device_id are described, and neither adds format detail beyond the schema. The mismatch actively misleads.

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

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

The description states a specific verb and resource: 'Get a single adopted device via the integration API.' This clearly separates it from the sibling list_integration_devices (plural) by specifying a single device. It stops short of naming the sibling explicitly, so it stays at 4.

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 list_integration_devices or get_mobility_device, nor any indication of prerequisites such as needing a valid controller or adopted device. The agent must infer the context from the name 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only implies a read via "Get" and "Returns" and says nothing about permissions, error behavior when the policy is missing, or how site_id/policy_id must relate.

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 Args/Returns layout is easy to scan and the purpose is front-loaded, but the Args block lists a phantom `settings` argument and the Returns line is redundant given an output schema exists. Efficient in shape but contains waste and an inaccuracy.

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

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

With no annotations and incomplete parameter coverage, the description should carry more weight, but instead it lists an argument that isn't in the schema while ignoring the one that is documented. An agent could be misled about the actual call signature.

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%, so the description must compensate, yet its Args list omits the documented `controller` parameter entirely and names a `settings` parameter that does not exist in the schema. It restates site_id/policy_id only at the trivial "Site identifier"/"DNS policy UUID" level, adding little and introducing a mismatch.

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

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

The description states a specific verb and resource ("Get a single DNS policy"), and "single" implicitly distinguishes it from the sibling list_integration_dns_policies. It does not explicitly name that sibling, so it falls just short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternative (list_integration_dns_policies). "via the integration API" is context, not usage routing.

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 signals a read operation and that it returns broadcast details, but says nothing about auth requirements, not-found behavior, or the 'via the integration API' constraint beyond mentioning it.

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 docstring-style Args/Returns layout is reasonably compact, but the Returns section restates what the output schema already provides, and the Args list contains a phantom parameter, so the structure includes waste and a defect.

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 single-item read with an output schema present, the description is nearly sufficient, but the mismatched 'settings' argument and the undocumented controller parameter leave gaps against a 33% schema coverage.

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% and the description introduces a 'settings: Application settings' argument that does not exist in the schema (which has site_id, controller, broadcast_id), while never explaining the controller parameter. This is inaccurate rather than merely thin.

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

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

The description states a specific verb+resource ('Get a single WiFi broadcast'), and the word 'single' implicitly distinguishes it from the list_integration_wifi_broadcasts sibling. It is clear but does not explicitly name that sibling, so it stays short of a 5.

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

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

Usage is only implied by 'single' versus the obvious list sibling; there is no explicit when-to-use/when-not statement, no mention of when to prefer list_integration_wifi_broadcasts, and no prerequisites. Adequate but with clear gaps.

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. "Get" implies a read, but nothing is said about required permissions, whether data is live or cached, rate limits, or controller selection behavior. For a metrics tool with zero annotation coverage this is a significant gap.

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?

It is short and front-loads the purpose sentence, but the boilerplate Args/Returns block includes an incorrect parameter and adds little value. The good part (aggregate-vs-site behavior) is buried after the misleading arg list.

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?

An output schema exists, so return values need not be re-explained, but the definition still omits usage guidance and references a non-existent parameter. For a cross-site metrics tool sitting among several health/metrics siblings, this leaves an agent without enough to call it correctly or confidently.

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 usefully explains site_id's optional/aggregate semantics, but it lists a "settings: Application settings" argument that does not exist in the schema, which is actively misleading. The controller parameter is only documented in the schema, and at 50% coverage the description does not compensate for the phantom/missing detail.

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 gives a specific verb+resource ("Get internet health metrics") and adds scope ("across sites"), so the agent knows this is a read of health metrics. However, it does not distinguish itself from siblings like get_site_health_summary, get_isp_metrics, or query_isp_metrics, which overlap heavily in the health/metrics space.

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 only usage signal is implicit: passing site_id returns per-site metrics and omitting it returns aggregates. There is no statement of when to prefer this over get_site_health_summary or query_isp_metrics, nor any 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?

With no annotations, the description carries the full behavioral burden. 'Get' implies a read, and the Returns section names the data fields, but there is nothing about auth requirements, rate limits, or scoping behavior. Worse, the Args section lists a 'settings' parameter that does not exist in the schema, adding misleading behavioral detail.

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 Args/Returns docstring layout is front-loaded and reasonably compact, but one of its two arg lines is a phantom parameter, so the structure is not clean. It is adequate but not 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?

An output schema exists, so return values need not be re-explained. But the description misstates the input parameters and does not address the ambiguity with query_isp_metrics, which is a serious omission for a tool that is nearly indistinguishable from a sibling.

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% and the description does not compensate: it restates site_id trivially as 'Site identifier' and omits the controller parameter entirely, while inventing a 'settings' parameter that the schema does not define. The description actively misleads rather than clarifying parameter meaning.

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

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

The description states a specific verb and resource ('Get ISP metrics') scoped to 'a specific site', which is clear. However, it gives no differentiation from the near-identical sibling query_isp_metrics, so an agent cannot tell the two apart from the text alone.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as query_isp_metrics or compare_site_performance. The agent must infer usage entirely from the name.

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 behavioral burden, and it adds almost nothing: no statement of what 'detail' includes, no read-only confirmation, no auth or controller-resolution behavior. Only the verb 'Get' weakly implies a non-mutating read.

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

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

A single short sentence with zero padding, so it is structurally clean and front-loaded. However, the brevity comes at the cost of under-specification rather than genuine economy, which caps this dimension.

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?

An output schema exists, so return values need not be described. But for a tool requiring two identifiers on a controller-scoped API, the description omits any hint about sourcing device_id/workspace_id or the controller resolution chain that the schema only partially covers.

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%: the controller parameter is documented in the schema, but device_id and workspace_id have no description anywhere. The tool description contributes no meaning about what these identifiers are or where to obtain them, so it fails to compensate for the coverage gap.

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

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

The description states a specific verb ('Get') and resource ('detail for a UniFi Mobility device'), making the retrieval intent unambiguous. It does not, however, differentiate itself from the closely named sibling list_mobility_devices or explain what distinguishes a single-device fetch from the list.

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 list_mobility_devices or list_mobility_device_clients, nor any stated prerequisite such as obtaining device_id from the list tool. Usage must be inferred entirely from the name.

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 is a read operation by naming convention, but it says nothing about permissions, whether the config must exist, or error behavior. The 'Returns' line only restates that config details come back.

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

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

Very short and front-loaded, but the Args/Returns block is padding: it repeats parameter names and states the obvious return. Efficient in word count but not information-dense.

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?

An output schema exists, so return values need not be explained. However, with no annotations and no usage guidance against several sibling get/list tools, the description is only minimally viable for correct selection and invocation.

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 50%; config_id is documented only by the description's 'Configuration identifier' and the controller parameter is documented in the schema itself with default and see list_controllers guidance. The description adds little 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?

States a specific verb (Get) and resource (SD-WAN configuration) qualified by ID, which is clear. It doesn't differentiate from the sibling list_sdwan_configs or get_sdwan_config_status, though the 'by ID' qualifier helps somewhat.

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 versus list_sdwan_configs (to find IDs) or get_sdwan_config_status (to check a config's state). An agent has no explicit routing 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, so the description carries the full burden, and it discloses almost nothing: no indication of whether the call is read-only, what happens if no config is deployed yet, or how large/streamed the status payload is. The 'Returns:' line merely restates the tool name.

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

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

The purpose is front-loaded, but the bulky 'Args:'/'Returns:' boilerplate duplicates the schema and the tool name respectively. Almost none of that text adds information, so the description is padded rather than concise.

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?

An output schema exists so return values need not be explained, but the description still omits the controller-selection context (the schema mentions list_controllers/select_controller, which the description never surfaces), gives no usage routing against siblings, and leaves config_id semantics unexplained.

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%: config_id is undocumented in the schema and the description only restates it as 'Configuration identifier' with no format or source (e.g. where to obtain it). It also lists a 'settings' argument that does not exist in the schema and ignores the meaningful controller-resolution behavior documented in 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 first line gives a specific verb+resource ('Get SD-WAN configuration deployment status'), which is meaningfully narrower than the sibling get_sdwan_config or list_sdwan_configs. However, it does not explicitly distinguish itself from those siblings, so an agent must infer the difference.

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

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

There is no when-to-use guidance, no contrast with get_sdwan_config or list_sdwan_configs, and no prerequisites (e.g. that a controller must be selected). The description gives no signal about when this tool is the right choice.

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 behavioral burden. It does disclose one useful trait, raising ResourceNotFoundError when the site is absent, but says nothing about permissions, scope, or what 'detailed' information is returned relative to sibling tools.

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 docstring layout (Args/Returns/Raises) is front-loaded and reasonably brief, but it spends lines on a nonexistent 'settings' argument and a redundant Returns line while omitting structure that would actually help selection.

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?

An output schema exists, so the return-value line is unnecessary; meanwhile the definition is missing the guidance an agent needs to pick this tool among dozens of site siblings. The stale Args section means the description no longer matches the actual interface.

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%: site_id has no schema description while controller does. The description's Args block describes site_id only superficially and, worse, lists a 'settings' parameter that does not exist in the schema while omitting the real 'controller' parameter, so it adds confusion rather than meaning.

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

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

The description names a specific verb and resource ('Get detailed site information'), so the basic purpose is clear. However, it does nothing to distinguish this from numerous close siblings that also return site data (list_sites, get_site_inventory, get_site_health_summary, get_integration_sites), leaving the agent to guess which 'site details' call applies.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the many site-related siblings. The agent gets no routing signal for choosing this over get_site_inventory or get_site_health_summary.

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 behavioral burden. 'Get' implies read-only and the None-scope behavior is noted, but there is no disclosure of permissions, rate limits, or what a 'health summary' actually contains. The phantom 'settings' argument further muddies the contract.

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?

Short and front-loaded, with the scope decision stated first. The 'Args:'/'Returns:' scaffolding is docstring boilerplate and the 'Returns: Health summary' line is redundant given the output schema, but there is little waste overall.

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?

An output schema exists, so return values need not be described. Still, for a two-parameter tool with no annotations and only 50% schema coverage, the description leaves gaps: it never contrasts this tool with its many siblings and mentions a parameter that is not in the schema.

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

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

Schema coverage is 50%. The description adds genuine meaning for site_id (optional; None returns all-sites summary) that the schema lacks. But it omits the controller parameter entirely and lists a 'settings: Application settings' argument that does not exist in the input schema, which is misleading.

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

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

States a specific verb+resource ('Get health summary') and clarifies the two scopes (all sites vs a specific site). However, it does not differentiate itself from closely related siblings like get_internet_health, compare_site_performance, or get_cross_site_statistics.

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 the site_id=None behavior but offers no when-to-use guidance relative to alternatives. Nothing tells an agent when to prefer this over get_site_details or get_internet_health.

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 behavioral burden. It implies a read ('Get') and describes the returned breakdown, but says nothing about permissions, rate limits, cost, or pagination for the all-sites case, which is a meaningful gap for a tool that can fan out across every site.

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 Args/Returns structure is easy to scan and the opening sentence is front-loaded, but the spurious 'settings' argument is dead weight and the 'Returns' block is redundant given the tool has an output schema.

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 an output schema present, the return format needn't be explained, and the description does state resource scope. But for a zero-annotation tool it leaves behavioral and sibling-selection context thin, and it references a non-existent parameter.

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%: controller is documented in the schema, while site_id is not, and the description usefully explains site_id ('If None, returns inventory for all sites'). However, it also lists a 'settings: Application settings' argument that does not exist in the schema (additionalProperties: false, only site_id/controller), which adds noise and potential confusion.

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

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

States a specific verb+resource ('Get comprehensive inventory for a site or all sites') and enumerates the contents (devices, clients, networks, SSIDs, VPN tunnels, firewall rules). It does not, however, distinguish itself from close siblings like get_site_details, list_all_sites_aggregated, or list_innerspace_inventory, so an agent cannot tell which to pick from the description alone.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The only scoping hint is that passing no site_id returns all sites, which is parameter behavior rather than tool-selection 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 carries the full behavioral burden, yet it only restates return contents (which the output schema already covers) and says nothing about auth, rate limits, or side effects. "Get" weakly implies a read, but no explicit safety or scope context is given.

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 text is short and front-loaded, but the Args block documents a nonexistent parameter and the Returns block duplicates what the output schema already provides, so parts of it do not earn their place.

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

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

For a simple optional-param read tool with a 100%-covered schema and an output schema, the description is close to adequate. However, the incorrect "settings" arg documentation leaves an agent with a misleading mental model of the interface, and no usage context is provided.

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%, giving a baseline of 3, but the description documents an arg named "settings: Application settings" that does not exist in the schema (the actual parameter is "controller"). This actively misleads about the parameter rather than clarifying it.

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

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

States a specific verb and resource ("Get API version control information") and names the returned versions (current, latest, deprecated), which makes the purpose unambiguous. No sibling appears to compete for this function, but the description doesn't explicitly differentiate itself from the controller/integration families.

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 call this tool, when not to, or which alternatives exist. The agent is left to infer usage entirely from the name.

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 states the tool returns status information but does not explicitly disclose that it is a read-only, non-destructive operation. For an AI agent, explicit safety guarantees 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 extremely concise with two sentences. Every word serves a purpose, making it easy to parse quickly 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?

The description is adequate for a simple health check with no parameters and an output schema. It covers the purpose and return value, though it could mention typical use cases like monitoring or startup verification.

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 no parameters, so the description does not need to add parameter semantics. Schema coverage is 100%, meeting the baseline for zero parameters.

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

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

The description clearly states the tool is for a health check to verify the server is running, using a specific verb and resource. It is distinct from all sibling tools which are focused on network, connector, and integration 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 implies usage when needing to verify server status, but does not explicitly state when to use or not use it, nor does it mention any alternatives. Given the clear purpose and lack of similar tools, implied usage is acceptable but not explicit.

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 behavioral burden, but it only names the upstream API and states the return is aggregated stats. It omits auth requirements, whether results are read-only, and any scoping/time-window behavior. Worse, its 'Args: settings' note does not correspond to any actual parameter.

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 one-sentence core is appropriately short and front-loaded, but the leftover Args/Returns boilerplate is redundant with the existing output schema and contains an inaccurate parameter name, so not every line earns its place.

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

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

An output schema exists, so return value detail is not strictly required, and the purpose line plus full-coverage schema parameter are adequate to invoke the tool. The incorrect 'settings' arg reference and absence of any usage context leave it only minimally 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 100%, so the real 'controller' parameter is well documented in the schema, establishing a baseline of 3. However, the description's Args block references a nonexistent 'settings' parameter instead of 'controller', which actively misleads rather than adding 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?

States a specific verb ('List') and resource ('all sites with aggregated stats'), and the 'aggregated' qualifier distinguishes it from the plain list_sites sibling. It does not explicitly name alternatives, but the core purpose is legible.

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 when-to-use or when-not-to-use guidance is given, which is a real gap given many overlapping siblings (list_sites, get_cross_site_statistics, compare_site_performance, get_site_health_summary). The agent must guess which one fits.

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 behavioral burden. It discloses the return shape ('count' and 'data'), but says nothing about pagination, auth/permissions, or result limits for what is presumably a large collection.

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, but it spends lines on a nonexistent 'settings' argument and a Returns block that is redundant given the output schema. Structure is fine, content is partly wasted.

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

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

For a simple read-only list tool with one fully documented parameter and an output schema, the definition is close to complete. The misleading 'settings' argument and the absence of any when-to-use guidance leave clear gaps.

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

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

Schema description coverage is 100% for the single 'controller' parameter, so the baseline would be 3. However, the description's Args section documents a 'settings: Application settings' parameter that does not exist in the schema, introducing misleading parameter information.

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

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

States a specific verb ('List') and resource ('UniFi Carrier Fabric service plans'), which is enough to separate it from the singular sibling get_carrier_service_plan. It does not explicitly name that sibling, but the list-vs-get distinction is inferable.

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 the many siblings, particularly get_carrier_service_plan (single plan) or list_carrier_subscribers. No prerequisites, context, or exclusions are given.

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

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

With no annotations, the description carries the full burden. It usefully discloses the return shape ('pagination info and data') and the available filters, but says nothing about read-only nature, auth/permission requirements, or pagination limits/defaults. It adds moderate value but leaves meaningful behavioral gaps.

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

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

The docstring is front-loaded with the purpose, then structured Args/Returns blocks. Every line earns its place, though the Args listing is a fairly mechanical restatement of parameter names.

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 zero-required-param list tool with an output schema already covering returns, the description is largely sufficient: purpose, filters, and return structure are all present. It could say more about read-only behavior and pagination defaults, but nothing critical for correct invocation is missing.

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 20% (just 'controller'), yet the description supplies meaning for four of the five params (limit, offset, plan_id, suspended) that the schema leaves undocumented. This is genuine added value over the schema, though the semantics are terse.

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

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

States a specific verb+resource ('List UniFi Carrier Fabric subscribers'), which an agent can distinguish from get_carrier_subscriber and create_carrier_subscriber. It does not explicitly name or differentiate from the nearest list sibling (list_carrier_service_plans), but the resource is unambiguous.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g. get_carrier_subscriber for a single record), and no prerequisites or context about when filtering is appropriate. The agent must infer usage entirely from the name.

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 and does disclose real behavior: the fallback resolution order (explicit argument → select_controller → default) and the per-session selection state. It does not explicitly label the operation read-only, but 'List' and the framing make the non-mutating nature unambiguous.

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

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

Front-loaded with the purpose in one line, followed by genuinely useful resolution context. The 'Returns' block partially restates what the output schema already provides, which is the only mild 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?

For a zero-parameter discovery tool with an output schema, the description supplies enough context: what it lists, how results are used, and how the default is resolved. The return enumeration duplicates the existing output schema rather than adding to it.

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 takes zero parameters, so the baseline is 4. The description also usefully clarifies the meaning of the `controller` argument on sibling tools, adding semantics beyond this tool's empty 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 first sentence states a specific verb+resource ('List the UniFi controllers this server can reach') and defines the scope of the read. It is clearly separable from siblings like select_controller, get_active_controller, and the many list_integration_* tools, which target other resources.

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 the downstream usage pattern (every controller-bound tool takes a `controller` argument drawn from this list) and names the resolution chain via select_controller and the default. It effectively tells the agent why and when to call this, though it does not explicitly state exclusions or a 'call this before X' prescription.

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

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

No annotations are provided, so the description carries the full burden. It discloses that results are paginated and that the list is canonical/global, but says nothing about auth needs, rate limits, or ordering. Adequate but not thorough for an unannotated 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?

Front-loads purpose well, but the Args list includes a phantom 'settings' parameter that adds confusion rather than information, and the Returns note is redundant given an output schema exists. Some sentences do not fully earn their place.

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

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

An output schema exists, so the return-value explanation is optional. The description covers scope and pagination adequately, but the nonexistent 'settings' arg and the unaddressed 'controller' parameter leave gaps an agent would have to resolve elsewhere.

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

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

Schema coverage is only 33%, so description help is needed. It does add value for limit (1-1000 bound) and offset (skip semantics), which the schema leaves undocumented, but it also lists a 'settings: Application settings' arg that does not exist in the schema, and it does not cover the controller parameter the schema documents.

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

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

States a specific verb+resource (list DPI application categories) and clarifies scope: it is global, not site-scoped, and returns the canonical list used by DPI and traffic-routing features. That distinguishes it from the site-scoped list_* siblings, though it does not name any specific alternative.

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 notes the endpoint is global rather than site-scoped, which is a usable usage signal, but it gives no explicit when-to-use/when-not guidance and does not point to any alternative tool. The agent must infer context on its own.

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 behavioral burden, and it discloses only that limit/offset paginate. It says nothing about the read-only nature, permissions, cross-controller scope, or what 'managed' means. Worse, it introduces a parameter ('settings') that the schema does not contain.

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

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

The purpose is front-loaded in a single clean sentence, but the Args/Returns block largely restates schema fields and includes a phantom 'settings' entry, so not every line earns its place.

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

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

An output schema exists, so the 'Returns' line is redundant, and the description omits the controller-targeting behavior entirely while listing a nonexistent parameter. For a list tool that can run against multiple controllers, that omission leaves a real 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?

The description documents limit and offset (already inferable from schema) but misnames a parameter as 'settings: Application settings' that does not exist in the schema, and entirely omits the 'controller' parameter — the one parameter that actually has a schema description and matters for execution. This is inaccurate rather than additive.

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

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

States a clear verb+resource ('List all managed hosts/consoles'), so an agent knows this is an enumeration tool. However it conflates two concepts ('hosts/consoles') and does nothing to distinguish itself from siblings such as get_host, list_controllers, or list_integration_devices, so the reader must infer scope from the rest of the catalog.

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

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

There is no when-to-use guidance, no conditions, and no named alternatives. Given the very dense sibling set (list_controllers, get_active_controller, list_integration_devices, etc.), the agent gets no help deciding when list_hosts is the right call.

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 full behavioral burden. It discloses only that a ValueError is raised when the cloud API is not enabled or console_id is empty, and does not clarify read-only status, side effects, pagination, or other operational traits. The mention of a 'settings' argument that is absent from the schema further weakens 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 short and front-loads the purpose, which is good. However, the Args block includes a non-existent 'settings' parameter and the Raises section is only marginally informative, so not every line earns its place.

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

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

An output schema exists, so return values need not be explained. For a two-parameter list tool, the description covers the required console_id and one error condition, but it omits the schema's controller parameter and contains a misleading settings parameter, leaving the definition only minimally 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 50%. The description usefully documents console_id as a Cloud Connector console UUID from list_hosts, but it omits the controller parameter entirely and incorrectly lists 'settings: Application settings,' which does not exist in the input schema. This introduces confusion rather than compensating for the coverage gap.

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

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

The description states a specific verb and resource: list access points known to InnerSpace on a console. It distinguishes this from other list_innerspace_* siblings by resource, though it does not explicitly contrast with alternatives such as list_innerspace_switches or list_hosts.

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 gives no when-to-use guidance or alternatives. It only notes that console_id comes from list_hosts, which helps locate a required value but does not explain when this tool should be chosen over sibling list 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses one failure mode (ValueError when the cloud API is not enabled or console_id is empty) and 'List' implies a read operation, but it is silent on pagination, permissions, or result volume.

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

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

The purpose is front-loaded and short, but the docstring-style Args/Raises layout is only partly effective: 'settings: Application settings' is a tautology describing a phantom parameter, wasting one line, while the Raises clause earns its place.

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

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

An output schema exists, so return values need not be described, and the Raises clause covers a key precondition. The mention of a nonexistent 'settings' parameter and the absence of any note about the controller default (which lives only in the schema) leave the picture slightly 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 50%: the schema documents 'controller' but not 'console_id'. The description compensates by explaining console_id's provenance (a Cloud Connector console UUID from list_hosts), which adds real meaning. However, it also lists a 'settings' argument that does not exist in the schema, creating confusion.

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

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

The description states a clear verb (List) and a specific resource (InnerSpace floor plans) scoped to a console, which lets an agent distinguish it from the Other InnerSpace siblings like list_innerspace_switches and list_innerspace_access_points. It does not explicitly name those siblings, but the resource is specific enough to route correctly.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives. The only implicit help is provenance for console_id ('from list_hosts'), which hints at a workflow dependency but is not a usage guideline.

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 disclose one real behavioral trait: a ValueError is raised when the cloud API is not enabled or console_id is empty. However it says nothing about pagination, return shape, or read-only semantics, and it lists a 'settings' argument that does not exist in the schema, which muddies the behavioral picture.

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

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

The purpose is front-loaded in a single clean sentence, but the following Args/Raises block is docstring boilerplate that includes a non-existent 'settings' parameter, so not every line earns its place.

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

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

An output schema exists, so return values need not be described. The definition covers the purpose, the required parameter's origin, and one error case, but omits how this list relates to the other InnerSpace list tools and gives no sense of result scope for an inventory query.

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% (controller is documented, console_id is not). The description compensates for console_id by stating it is a Cloud Connector console UUID obtained from ``list_hosts``, which adds genuine provenance value. But it introduces a phantom 'settings: Application settings' argument absent from the schema, offsetting the gain.

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

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

States a specific verb and resource with a meaningful scope qualifier: 'List unplaced devices in InnerSpace inventory on a console.' The word 'unplaced' usefully distinguishes it from sibling listers like list_innerspace_switches or list_innerspace_access_points, though it never names those siblings or explains the relationship.

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

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

There is no when-to-use guidance and no alternatives are named, despite many sibling list tools (list_innerspace_switches, list_innerspace_access_points, list_innerspace_floor_plans). The only routing hint is that console_id comes from ``list_hosts``, which is a dependency, not usage guidance.

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

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

With no annotations, the description carries the full burden, and it does disclose one real behavioral fact: a ValueError is raised when the cloud API is disabled or console_id is empty. However it never states the operation is read-only, gives no permission/authentication requirements, and does not address the mismatch between the documented 'settings' argument and the actual schema.

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 Args/Raises structure is compact and front-loads the purpose before the parameter notes. The only waste is the phantom 'settings' line, which adds noise without corresponding to any real input.

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?

An output schema exists, so return values need no explanation, and the error condition is covered. The gap is the undocumented 'controller' parameter (whose defaulting behavior is only visible in the schema) plus the spurious 'settings' entry, leaving the definition incomplete for a 3-parameter tool.

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

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

Schema description coverage is only 33%, so the description must compensate, and it partially does: console_id is annotated with its source (``list_hosts``) and site_id is explained as an optional site filter. Against that, the required 'controller' parameter is never mentioned and the documented 'settings' argument does not exist in the schema, leaving the parameter surface partly undocumented and partly misleading.

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

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

The description names a specific verb and resource ('List switches placed on InnerSpace floor plans on a console'), which is distinguishable from siblings like list_innerspace_access_points and list_innerspace_floor_plans. It does not, however, explicitly differentiate itself from those siblings or state its scope relative to the rest of the InnerSpace family.

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

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

There is no when-to-use guidance and no named alternative, only a pointer that console_id comes from ``list_hosts``. That prerequisite hint is useful, but an agent still has to infer under what circumstances this list tool is preferable to the other InnerSpace or inventory listing 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 are provided, so the description carries the full burden. It discloses pagination ('Paginated list') and the limit bound (1-1000), which is useful, but says nothing about auth requirements, default page size, ordering, or the controller-selection side effects that other tools imply.

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

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

The purpose sentence is front-loaded and the Args/Returns layout is scannable and short. However, the Args block includes a phantom 'settings' entry and duplicates schema field names, so not every line earns its place.

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

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

An output schema exists, so return values need not be explained, but for a 4-parameter list tool with no annotations the description is still thin. It omits the controller parameter entirely and misstates the parameter set, leaving real gaps an agent must close from the schema.

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

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

Schema coverage is only 25%, and the description does not fully compensate. It adds the 1-1000 range for limit (absent from the schema), but lists a 'settings' argument that does not exist in the schema and omits 'controller', which does. This mismatch undermines confidence in the documented parameters.

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

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

States a specific verb+resource ('List connected clients via the integration API'), so an agent can distinguish it from siblings like get_integration_client (singular) and list_integration_devices. It lacks explicit differentiation language, but the resource is unambiguous.

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

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

No when-to-use or when-not-to-use guidance is given. The description never explains how this differs from get_integration_client or when to prefer it over other list_* siblings, leaving the agent to infer usage from the name 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?

No annotations are provided, so the description carries the entire burden, yet it says nothing about permissions, auth scope, rate limits, or what 'adopted' means for results. It only notes pagination. It also lists a 'settings' argument that does not exist in the schema, adding confusion rather than 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 Args/Returns layout is front-loaded and reasonably compact, and the Returns line is tolerable even though an output schema already exists. But it wastes space on a nonexistent 'settings' argument and omits a real one, so structure is adequate but not clean.

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?

An output schema exists, so return-format explanation is unneeded. However, for a 4-parameter tool the description misdocuments the parameter set (phantom 'settings', missing 'controller') and gives no usage context, leaving the agent with an inaccurate picture of how to call it 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 only 25% (just 'controller'), so the description should compensate but only partially does. It adds useful detail for site_id (UUID or internal reference) and limit (1-1000), but introduces a phantom 'settings' parameter absent from the schema and completely omits the real 'controller' parameter, which the schema documents and which ties into select_controller.

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

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

States a specific verb and resource ('List adopted devices via the integration API'), which clearly separates it from sibling read endpoints like list_integration_clients or list_integration_networks. However, it does not explicitly differentiate itself from the closely related get_integration_device or list_integration_device_tags, so it falls short of a full 5.

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 versus alternatives such as get_integration_device or the broader device-listing siblings. There are no prerequisites, exclusions, or conditions described; the agent must infer that this is the paginated site-scoped lister.

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 behavioral burden, yet it discloses only that the result is paginated. It says nothing about read-only nature being enforced, permission/tenant requirements for the integration API, rate limits, or what happens for an unknown site_id. The 'Paginated list' return claim is also largely redundant given an output schema exists.

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 functional statement is front-loaded in one clean sentence followed by a compact Args/Returns block, with no filler. The only waste is the phantom 'settings' line, which occupies space while conveying nothing actionable.

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