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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds only a restatement of returned fields, with nothing about auth requirements, ID validity/not-found behavior, or any operational constraint.

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 but is followed by a very long dump of return keys, nested sub-keys and even a docs version tag ('7.3.70 docs'). Since an output schema exists, this enumeration is largely wasted text and bloats the definition well past what is needed to select and call the tool.

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

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

For a single-parameter read tool with an output schema supplied, the essentials (what it returns, which ID to pass) are covered. The bulk of the description is redundant with structured data rather than filling real gaps like error or not-found behavior, so it is adequate but not complete in the places that would actually help.

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 'id' parameter, which already states it is the 'Alarm hub ID'. The description's 'by ID' adds no format, source, or lookup guidance (such as where to obtain the ID) beyond the schema, so the baseline 3 applies.

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?

Starts with a specific verb and resource ('Get full details for a specific alarm hub by ID'), which is unambiguous and clearly distinct from the list-style siblings like protect_list_alarm_hubs. It stops short of naming that sibling explicitly, so an agent must infer the retrieval-vs-enumeration split from the name pattern.

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: the caller is expected to already hold a hub ID. There is no explicit guidance on when to reach for this tool versus protect_list_alarm_hubs (e.g. 'use the list tool to discover IDs'), and no prerequisites or failure conditions 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?

Annotations already declare a safe, read-only, closed-world read. The description adds little behavioral context beyond enumerating return fields, and since an output schema exists that enumeration is largely redundant. No mention of auth needs, error behavior, or lookup failure semantics.

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 front-loaded sentences; the retrieval purpose leads and the field list follows. Slightly wasteful because the return-field enumeration duplicates what the output schema already provides, but overall tight.

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?

A simple one-param getter with a full output schema and covering read-only annotations needs little more than a clear purpose statement. The description is complete for correct invocation, though it adds no scoping constraints or error guidance.

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

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

With 100% schema description coverage and a single required 'id' parameter documented in the schema, the description's 'by ID' adds nothing beyond structured data. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (get) and resource (bridge) with a qualifying scope ('specific bridge by ID'), which implicitly distinguishes it from the sibling protect_list_bridges. It does not name the list alternative explicitly, so it falls just short of the top bar.

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 via 'by ID' - the agent can infer this is the single-item counterpart to protect_list_bridges. There is no explicit when-to-use, when-not-to-use, or named alternative, so guidance is adequate but inferential.

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

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

Annotations already cover the read-only, non-destructive, closed-world profile, so the bar is lower, and the description still adds real value by enumerating the returned field set and explicitly naming what is NOT exposed (recording state, motion events, zones, channel/RTSP config). That negative-space disclosure prevents wasted calls, though error/timeout behavior is unaddressed.

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 core action, then two sentences that each carry non-obvious information (identical field set, excluded data). The field enumeration is long but functional; the version parenthetical is defensible evidence but slightly incidental.

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?

Output schema exists so return values need no prose, yet the description still summarizes the payload and its limits. For a single-ID lookup with full annotation coverage, nothing an agent needs to invoke it correctly 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?

There is only one parameter and schema description coverage is 100% ('Camera ID' with a pattern constraint), so the schema already does the heavy lifting. The description adds no format or lookup guidance beyond saying 'by ID'.

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 details for a specific camera by ID') and explicitly differentiates itself from the sibling protect_list_cameras by asserting the by-ID payload is identical to the list entry payload. An agent can tell exactly what this returns without opening either schema.

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 note that there is 'no extended/by-id-only payload' implicitly tells the agent this call is not needed for richer data, but it never states when to prefer this over protect_list_cameras or what an invalid/missing ID yields. 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description contributes the field inventory and a version-verification note, which is beyond the annotations, but it says nothing about error behavior for unknown IDs or pagination (none expected).

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 the first clause, then the return fields. The long field enumeration is somewhat bloated given an output schema exists, but nothing is misleading or 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?

The description is sufficient for a single-parameter read tool whose annotations carry the safety profile and whose output schema carries the return shape. The return-field list duplicates the output schema rather than filling a gap, but no information an agent needs to invoke it 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?

With one parameter and 100% schema description coverage, the schema already documents the 'id' field and its pattern. The description adds no syntax, format, or sourcing guidance beyond restating that lookup is by ID, so the baseline of 3 applies.

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 full details for a specific chime by ID'), which cleanly separates it from the list-style siblings like protect_list_chimes. It does not name a sibling explicitly, but 'by ID' makes the selection 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?

Usage is only implied: the phrase 'by ID' signals that a chime identifier is required, which an agent must obtain from protect_list_chimes first. No explicit when-to-use, prerequisite, or when-not guidance is given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that — no auth requirements, no behavior on an invalid/unknown ID, no note on whether the response is cached or live — and its one added element, the return-field list, 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 purpose sentence is front-loaded and efficient, but the second sentence is a sprawling nested enumeration of return fields that duplicates the output schema and roughly doubles the length without adding selection value. The trailing '(7.3.70 docs)' citation is noise for an invoking agent.

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

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

With read-only annotations, a fully documented single required parameter, and an existing output schema, the description covers what an agent needs to invoke the tool correctly. The main residual gap is the absence of any routing hint to protect_list_fobs for obtaining a valid ID.

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?

There is a single parameter with 100% schema description coverage ('Fob ID' plus a format pattern), so the schema fully documents it. The description adds no syntax, source, or format guidance for the id, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Get full details for a specific fob by ID'), which is unambiguous and implies the get-vs-list distinction against protect_list_fobs. However, it never names the sibling or explicitly contrasts single-fetch with enumeration, so an agent must infer the relationship from naming convention 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?

Usage is only implied: the 'by ID' phrasing suggests calling this when you already hold a fob ID and need its full record. There is no explicit when-to-use, when-not-to-use, or pointer to protect_list_fobs for discovering IDs, which is the natural precondition for this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the return payload (applicationVersion), which is redundant with the existing output schema, so it contributes little beyond the annotations.

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

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

Two short, front-loaded sentences with no filler; the purpose leads and the return value follows. Every clause 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?

For a zero-parameter read tool with full annotation coverage and an output schema, almost nothing is missing. The only gap is the absence of a note on when the info is useful (e.g., version/compatibility checks), which would help an agent decide to call 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 correctly implies a no-argument invocation and adds nothing that could mislead about 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 and resource ("Get UniFi Protect application information") and scopes it to the application itself rather than a device. It is implicitly distinct from the many list_*/get_* device siblings, but never explicitly says "application-level, not a device" to differentiate it.

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: the tool is the sole application-info tool among device-centric siblings, so an agent can infer it is for app metadata. There is no explicit when-to-use, when-not-to-use, or named alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without the description. The description adds nothing behavioral beyond that (no auth scope, error behavior, or freshness semantics), and its enumerated field list largely duplicates 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?

Purpose is correctly front-loaded in the first clause, but the long inline enumeration of return fields and the trailing '(7.3.70 docs)' citation consume most of the text without aiding tool selection. Since an output schema already exists, that field list is redundant rather than 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?

For a single-parameter, read-only fetch with a full output schema and clear annotations, the description covers what an agent needs in order to call the tool correctly. The only missing piece is routing context against the list/get sibling pair.

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 single 'id' parameter is documented in the schema with a pattern constraint. The description restates only that lookup is 'by ID' and adds no format, uniqueness, or sourcing detail beyond the schema, so baseline 3 applies.

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 (light) with clear scope ('full details ... by ID'), distinguishing a single-item fetch from the sibling list tool protect_list_lights by implication. It does not explicitly name that sibling, so an agent must infer the retrieve-one vs enumerate-many split from naming 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 guidance on when to use this versus protect_list_lights or the broader family of protect_get_* tools, and no stated prerequisite such as needing an ID obtained from a list call. The 'by ID' phrasing only weakly implies the lookup flow.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds value by enumerating the rich return payload (alarmHub fields, threadState, ledSettings), which is genuinely useful context beyond the annotations, but it does not discuss auth, rate limits, or failure modes.

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 crisp and front-loaded, but the second sentence is an enormous field enumeration that repeats the output schema (which already exists per context signals) and is hard to scan. Much of that field list is redundant with the declared output schema and harms readability.

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

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

For a single-param read tool with a declared output schema, the definition covers purpose, disambiguation, and return shape, so an agent can call it correctly. The verbatim field dump duplicates the output schema rather than adding explanation, leaving minor room to improve.

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 single id parameter is fully documented with a pattern, so the schema already carries the semantics. The description reinforces that id is a 'link station ID' and disambiguates it from alarm-hub IDs, adding marginal value beyond the schema baseline of 3.

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

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

States a specific verb (Get) and resource (link station) with scope (full details, by ID). It actively disambiguates from the sibling protect_get_alarm_hub by explicitly noting that link stations are non-alarm-hub gateways and routing alarm-hub callers to protect_list_alarm_hubs.

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

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

The description clearly establishes context by contrasting link stations with alarm hubs and pointing to protect_list_alarm_hubs for alarm hubs. However, it does not mention protect_list_link_stations as the way to discover IDs, and no explicit when-not-to-use condition is given beyond the alarm-hub exclusion.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the PATCH-replaces-slots semantics, which affects how an agent orders calls. It omits error/not-found behavior for an invalid ID.

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, then the return shape, then the PATCH caveat in three tight sentences. The enumerated return fields are somewhat redundant given the tool has an output schema, costing a little 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 read-only, single-parameter tool with an output schema, the description covers the essentials and adds the one non-obvious workflow detail (slots must be fully supplied on PATCH because it replaces the array). No pagination or failure-mode notes, but nothing critical 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?

There is a single required parameter with 100% schema description coverage and a documented pattern, so the schema carries the parameter meaning. The description's 'by ID' adds nothing beyond it, which is the expected baseline 3 when schema coverage is complete.

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 details for a specific live view by ID'), which is enough to separate it from the sibling list tool protect_list_liveviews, since 'by ID' implies single-item retrieval. It never names that sibling explicitly, 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?

Gives a concrete usage condition: fetch the full slot list when updating because PATCH replaces the slots array, which tells the agent when this call is required. It does not explicitly contrast with protect_list_liveviews as the alternative for enumerating views, so there is no exclusion 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?

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, so the safety profile is covered. The description goes beyond that by detailing the returned structure and, notably, linking outputs[].id to protect_activate_relay_output's outputId parameter, which is genuinely useful cross-tool context.

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

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

Purpose is front-loaded, which is good, but the bulk of the text enumerates the full return shape even though an output schema already exists, making much of it redundant. It is dense and structured but not every 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?

For a simple read-only single-parameter tool with a full output schema and complete annotations, the description is more than sufficient and even adds the cross-tool outputId link. Only minor edges (e.g., not-found behavior) are absent, which is acceptable here.

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 'id' parameter, so the schema already documents it fully. The description's 'by ID' adds no format, source, or semantics beyond what the schema provides, warranting the baseline 3.

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

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

States a specific verb+resource ('Get full details for a specific relay by ID'), which an agent can distinguish from the list-style sibling protect_list_relays. However, it never explicitly names or contrasts with that sibling, so 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?

The description gives no when-to-use guidance, no prerequisites, and no exclusions or references to alternatives like protect_list_relays or protect_get_info. 'By ID' only weakly implies that an ID must already be known.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds real value on top by disclosing the return shape (high/medium/low/package, null-or-absent when inactive) and warning that each URL is a bearer credential for live video that should not be repeated unprompted. That security caveat is behavior an annotation cannot express.

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

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

Three tight sentences: what it does, what it returns, what to do instead, plus the credential caution. Everything is front-loaded and each sentence adds non-redundant 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, yet the description still explains the quality keys and null-when-inactive semantics, and it covers the sibling hand-off and the security constraint. Nothing an agent needs to call this correctly 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 description coverage is 100% and there is a single 'Camera ID' parameter, so the schema carries the burden; the description only implies the id refers to a camera without adding format or constraint detail. Baseline 3 is appropriate for a one-parameter tool fully documented in 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 ('Get active RTSPS stream sessions for a camera') and scopes it precisely to the RTSP-stream concept. The sibling tools are all list/get entity tools, so a stream-session getter is clearly distinct, and the reference to protect_create_rtsp_stream further anchors it.

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

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

Explicitly routes the agent to protect_create_rtsp_stream when it needs to start a session, which is genuine when-to-use guidance. It stops short of stating when not to call this tool (e.g. non-camera devices or no-session cases), so it is clear context rather than full 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond that — no auth requirements, no rate limits, no error or not-found semantics — and instead spends its budget restating return fields.

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 a well-formed, front-loaded purpose statement, but everything after it is a sprawling enumeration of return fields. Since an output schema exists, that enumeration is largely redundant and dominates the description's length.

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 single-parameter read tool with a full output schema and safety annotations, the core need is covered by the first sentence. The remaining text re-describes the return payload the output schema already defines, so the description is verbose in the wrong place and silent on genuinely useful details like not-found 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?

With 100% schema description coverage and a single parameter fully documented as 'Sensor ID' with a pattern, the schema carries the meaning and the baseline is 3. The phrase 'by ID' adds nothing about format or sourcing of the ID beyond what the schema already specifies.

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 states a specific verb (Get), resource (sensor), and scope (by ID, full details), which distinguishes it from the sibling protect_list_sensors in practice. It never names the sibling or any alternative explicitly, but the get-vs-list distinction is implicit in 'by ID'.

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 protect_list_sensors or the other protect_get_* siblings, no prerequisite for obtaining a valid sensor ID, and no error behavior for unknown IDs. The description only says what it returns, not when to reach for it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond that (no auth requirements, error behavior, or freshness guarantees), leaning instead on enumerating return fields.

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 is front-loaded in the first sentence. The trailing return-field enumeration is long and largely duplicates the existing output schema, but it is compactly expressed and does not obscure the core statement.

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 single-parameter read tool with a full output schema and rich annotations, the description covers the essentials. Since an output schema exists, the enumerated return fields are redundant rather than necessary, and the missing piece is routing guidance against sibling getters/lists.

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?

There is a single parameter with 100% schema description coverage ('Siren ID', with pattern constraint), so the schema carries the semantics. The description adds nothing about format or constraints beyond restating 'by ID', which is the expected baseline here.

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 full details for a specific siren by ID'), which cleanly separates it from the list-style sibling protect_list_sirens. It stops short of naming the sibling or scope limits explicitly, so it is clear but not fully differentiated.

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 phrase 'by ID' implies you already have an identifier, which is the only real usage signal. There is no explicit when-to-use guidance and no mention of alternatives such as protect_list_sirens for discovering IDs, so context is left to inference.

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

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

Annotations only declare readOnly/destructive/openWorld; the description goes further by disclosing failure modes (HTTP 503 when the camera is offline or unreachable), an oversize-image refusal, and a concrete remediation ('try without highQuality'). It also notes clients render the image directly, so the agent knows what to expect from a read with no 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?

Four sentences, all front-loaded: what it returns first, then parameter modifiers, then failure modes and recovery. Every sentence carries operational information with no filler.

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

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

With no output schema, the description supplies the return contract (base64 JPEG rendered by clients) and covers the error paths an agent must handle. For a read-only snapshot tool with 3 well-documented params, nothing material 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 100% and each parameter is already documented, so the baseline is 3; the description still adds value by tying highQuality to the 1080p-or-higher guarantee and to the size-refusal behavior, and by restating the package-camera prerequisite. The overlap with the schema keeps it from a full 5.

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 a JPEG snapshot from a camera') plus the concrete return payload ('base64-encoded image/jpeg'). This clearly separates it from siblings like protect_get_rtsp_streams (live stream) and protect_get_camera (metadata) without opening their 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?

Gives clear conditions for the optional parameters (highQuality for 1080p+, channel=package only for cameras with hasPackageCamera=true) and a fallback path when the response is too large. It does not, however, state when to prefer a snapshot over alternatives such as the RTSP stream tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false. The description only lists return fields, which are already covered by the output schema, and adds no behavioral context such as auth needs, rate limits, or error handling.

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

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

The first sentence is front-loaded and efficient. The second sentence enumerates many return fields that are redundant with the existing output schema, adding length without new value.

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

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

For a simple getter with an output schema and safety annotations, the description covers the operation, the required ID, and the returned fields. It lacks usage routing to sibling tools, but that is a minor gap for an obvious single-item retrieval.

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%, and the schema already documents the sole 'id' parameter as 'Speaker ID'. The description's 'by ID' adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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 full details for a specific speaker by ID'), making the operation clear. It does not differentiate from sibling tools like protect_list_speakers, 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?

Provides no explicit when-to-use, prerequisites, or alternative tools. 'By ID' is a parameter constraint, not guidance on choosing this tool over protect_list_speakers or other getters.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description contributes the returned field list, but says nothing about auth requirements, error behavior for an unknown ID, or pagination concerns — acceptable but not rich.

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 tight sentences, zero filler, with the identity/scope qualifier front-loaded before the return-value enumeration.

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 single-parameter read tool with full schema coverage, safety annotations, and an output schema, nothing an agent needs in order to call it correctly 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 description coverage is 100% and the single 'id' parameter carries its pattern and description in the schema, so the description's 'by ID' adds no syntax or format detail. Baseline 3 for a fully documented single parameter.

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

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

States a specific verb (Get) and resource (UniFi Identity/ULP user), qualified by ID lookup, which cleanly separates it from protect_list_ulp_users and from the similarly named protect_get_user. An agent can pick this tool without opening the schema.

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 'by ID' — you call it when you already hold a ULP user ID — but the description never states when to prefer this over protect_list_ulp_users or protect_get_user, nor any prerequisites. Adequate but with an obvious routing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the returned field list, which is largely duplicated by the output schema, and omits error or permission 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?

Two sentences, purpose first and return fields second, with no wasted words. The field list is somewhat redundant with the output schema but remains short and scannable.

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?

Simple read-by-ID tool with full annotation coverage and an existing output schema, so the description is nearly complete for calling it correctly. The only gap is no explicit disambiguation from protect_get_ulp_user, but the core invocation needs nothing more.

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% with 'User ID' and a pattern constraint; the description adds only 'by ID', which restates the schema. Baseline 3 is appropriate because the schema fully documents the single parameter.

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

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

States a specific verb (Get details), resource (Protect user), and selector (by ID), plus the returned field shape. It does not explicitly differentiate from sibling protect_get_ulp_user, another user-fetching tool, so sibling discrimination 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?

Implies usage when you have a user ID and need details for that single user, and notes field parity with protect_list_users entries. However, it never states when to prefer this over protect_list_users or protect_get_ulp_user, so guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond that (no auth requirements, no error behavior for an unknown ID); its field list is return-shape information, not 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?

Two short sentences, front-loaded with the purpose and free of filler. The enumerated return fields are slightly wasteful given an output schema exists, but the whole description is brief enough that it doesn't harm readability.

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

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

For a simple read-by-ID tool with full annotation coverage and an output schema, the description covers what an agent needs to select and invoke it. Nothing essential is missing, though it could note the read-only nature or behavior on an invalid ID.

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

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

With a single parameter at 100% schema description coverage ("Viewer ID" plus a pattern constraint), the schema already carries the semantics. The description's "by ID" adds nothing beyond the schema, so the baseline 3 applies.

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 full details for a specific viewer by ID"), which cleanly separates it from the sibling protect_list_viewers. It does not name the sibling explicitly, but "by ID" versus listing 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?

Usage is only implied: an agent can infer this is the follow-up call after obtaining an ID from protect_list_viewers. There is no explicit when-to-use, when-not-to-use, or named alternative, so it lands at minimum viable.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it returns an array, and paged results also carry totalCount and offset. It stops short of describing ordering or rate limits.

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 clause is well front-loaded, but the middle is a sprawling enumeration of every nested field (ledSettings, alarmHub with a dozen sub-keys, threadState, etc.) that largely duplicates the existing output schema. This bulk crowds out the one actionably useful sentence, the pagination guidance.

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, return values need not be restated, and annotations cover safety; the pagination behavior is the piece that genuinely mattered and it is included. Nothing an agent needs to call this correctly is missing, though a pointer to the sibling get tool would round it out.

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

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

Schema coverage is 100%, so baseline would be 3, but the description goes beyond the terse schema strings by explaining the paging rationale (large sites) and the side effect of a paged call (totalCount and offset in the response). That gives the two parameters purpose the schema alone does not.

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 ('alarm hubs managed by UniFi Protect'), and the plural/singular pairing with the sibling protect_get_alarm_hub is immediately clear. An agent can distinguish it from the get-by-id sibling without opening either schema.

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 gives pagination guidance ('On a large site, use limit and offset to page') but never states when to use this tool versus protect_get_alarm_hub or why a listing is preferable to a lookup. Usage is implied by the list-vs-get naming convention rather than made 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower; the description still adds real context about the returned array shape, the effect of paging (totalCount and offset appear), and the discrete activationDelay values. It omits permission/auth requirements and default page size, which keeps it out of the top band.

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?

One dense paragraph, front-loaded with purpose and scope, then return shape, then paging guidance — a sensible order with no filler sentences. Slightly overstuffed for a two-parameter list tool, and the '(7.3.70 docs)' citation is incidental metadata that does not help invocation.

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

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

Covers purpose, availability constraint, return fields, and paging behavior; an output schema exists so return values need not be spelled out (though it does so usefully). The remaining gap is default behavior when no limit is supplied — an agent cannot tell whether the call returns everything or is capped.

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 limit/offset are already documented, giving a baseline of 3. The description adds operational meaning beyond the schema by explaining that these are the paging knobs to use on a large site and that using them changes the response shape (adds totalCount/offset).

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 all arm profiles') and immediately disambiguates the scope: local alarm manager / standalone NVR, explicitly not Protect cloud alerts. An agent can tell what this returns and which system it applies to without opening the schema.

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?

Gives an explicit when-not condition (only available with the local alarm manager, not cloud alerts) and directs the agent to use limit/offset for paging on large sites. It does not name an alternative tool, but with no sibling arm-profile tools there is no meaningful alternative to route to.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real behavioral context beyond that: the return is an array, and a paged result additionally carries totalCount and offset. It does not cover rate limits or auth requirements, but for a read-only list tool this is solid.

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 is front-loaded in the first sentence, followed by return shape and then paging advice, so the structure is sound. The full enumeration of every returned field is somewhat long given that an output schema exists and already carries that information, which is the only real inefficiency.

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 collection tool, the description, annotations, complete parameter schema and existing output schema together leave no critical gap: the agent knows what it lists, that it is safe, and how to page. Listing return fields is redundant with the output schema rather than filling a hole, so it does not reach a 5.

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

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

Schema description coverage is 100%, so both limit and offset are already fully documented in the schema. The description adds a modest amount of meaning by explaining when paging is warranted ('on a large site') and what a paged result includes, but this is incremental rather than compensating for a gap, so the baseline of 3 applies.

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 all bridges managed by UniFi Protect'), and the word 'all' signals the unfiltered, collection-level scope that separates it from the sibling protect_get_bridge. It does not explicitly name that sibling, so it falls just short of the top score.

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 gives conditional guidance for the parameters ('On a large site, use limit and offset to page'), which is useful, but says nothing about when to prefer this tool over protect_get_bridge or the subscription tools, and offers no exclusions or prerequisites.

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

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

Annotations only cover the read-only safety profile; the description adds substantial non-obvious behavior — the API version the fields were verified against, a full field inventory, explicit omissions, and the fact that a paged result additionally returns totalCount and offset. It also warns that guid is a shared model identifier, not a per-camera id, which is exactly the kind of trap an agent would otherwise fall into.

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 core purpose, but the bulk of the text is a long enumeration of every returned field, which duplicates the declared output schema and is not needed for tool selection. The genuinely useful bits (pagination, exclusions, the guid caveat) are buried inside that enumeration rather than given precedence.

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 field list is over-delivery rather than a necessity; the description still covers what an agent needs to call this correctly — scope, paging, and known data limitations. Nothing required 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 100% with descriptions for both limit and offset, so the baseline is 3. The description adds value by explaining the paging contract — that using limit/offset on a large site yields totalCount and offset in the response — which tells the agent how the parameters behave in combination, not just individually.

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 all cameras managed by UniFi Protect' — and reinforces list semantics by noting it returns an array and supports paging. It never names the sibling it must be distinguished from (protect_get_camera), so an agent must infer the list-vs-single distinction from the wording 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?

Gives concrete usage context: 'On a large site, use limit and offset to page.' It also functions as negative guidance by enumerating data the Integration API does NOT expose (recording state, motion timestamps, firmware, host), steering the agent away from wasted calls. It stops short of explicitly routing between this tool and protect_get_camera.

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

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

The annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it states the response is an array, enumerates chime fields, and explains pagination behavior including totalCount and offset on paged results.

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 purpose and then supplies return details followed by pagination guidance. The explicit field enumeration is somewhat redundant given the output schema exists, but the text is dense and every sentence is informative rather than repetitive.

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

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

For a simple two-parameter list tool with annotations and an output schema, the description is fully sufficient. It states the scope, return structure, and pagination behavior, so an agent has everything needed to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, so both limit and offset are already documented in the input schema. The description adds meaning by explaining the use case for paging on a large site and noting that paged results return totalCount and offset, which goes beyond the raw schema bounds.

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 and resource: 'List all chimes managed by UniFi Protect.' It clearly distinguishes this bulk-listing tool from the sibling protect_get_chime single-resource tool through 'all' and 'List'. No ambiguity about what the tool returns.

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 pagination guidance for large sites, which implies when to use limit and offset, but it does not explicitly say when to use this tool versus protect_get_chime or any other sibling. Usage is inferable from 'List all chimes' rather than directly 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?

Annotations already cover safety (readOnly, non-destructive, closed-world), yet the description adds real behavioral context: the asynchronous creation of a derived '<name>.gif' preview record, and the warning that a listing taken right after an upload may show only the stored image. The field enumeration ('verified live 7.3.70') is largely redundant given an output schema exists, which keeps this from 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 scope and constraint, then the async caveat, then paging guidance — a sensible ordering. It is dense but each clause carries information, except the enumerated record fields, which duplicate 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?

For a read-only list tool with an output schema and full parameter coverage, the description supplies exactly the missing context: the single supported file type, the async derived-preview caveat, and how to paginate a large site. Nothing needed to invoke it correctly appears to be absent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description nevertheless adds meaning beyond the schema: that limit/offset are the paging mechanism and that a paged result additionally returns totalCount and offset, which is behavior the schema alone does not convey.

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 device asset files') and immediately narrows the scope to a single supported type ('only animations is supported — clips uploadable to G4 Doorbell screens'). Sibling list tools all target different resources (cameras, lights, chimes), so naming this resource is sufficient to tell it apart.

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?

Gives conditional guidance on paging ('On a large site, use limit and offset to page'), which is useful and actionable. However it never states when to call this tool versus other listings or what the required fileType effectively forces, so usage remains implied rather than 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral context: it lists the returned fob fields in detail and explains that paged results also return totalCount and offset. This extra information goes beyond the annotations and helps an agent understand the response shape 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?

The description is front-loaded with the tool's purpose, followed by return field details and a pagination note. It is somewhat lengthy due to the field enumeration, but every part serves to inform the agent. No rambling or redundant sentences.

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

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

Given the presence of an output schema and safety annotations, the description is largely complete. It covers purpose, return shape, and pagination. It lacks explicit alternative-tool guidance, but for a simple list operation with structured output, this is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context for limit and offset by explaining they are used to page on large sites and that a paged result returns totalCount and offset. This clarifies the intended use beyond the schema's generic parameter descriptions.

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

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

The description states a specific verb and resource: 'List all fobs managed by UniFi Protect.' This clearly distinguishes it from the singular sibling protect_get_fob by implying a collection, but it does not explicitly name alternatives. An agent can infer the purpose without opening the schema.

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 offers pagination guidance ('On a large site, use limit and offset to page'), which is useful for parameter usage, but it gives no guidance on when to choose this tool over alternatives like protect_get_fob or other list tools. No selection criteria or exclusions are provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description does add one genuinely behavioral detail — that a paged result also returns totalCount and offset — but the long field enumeration duplicates the existing output schema rather than adding traits.

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

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

The purpose is correctly front-loaded in the first sentence, but the following field-by-field enumeration is a long, low-value block that largely restates what the output schema already provides. The paging note at the end is the only additional sentence that 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?

With annotations covering safety and an output schema covering return shape, the description only needs to add operational context — which it does via the paging/totalCount note. Nothing essential for calling the tool correctly is missing, though the list-vs-get routing is left implicit.

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

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

Schema description coverage is 100%, so both parameters and their bounds are already documented, making the baseline 3. The description's note that limit/offset are for paging on large sites reinforces intent but adds no syntax or constraint detail 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 and resource with scope ('List all lights managed by UniFi Protect'), which is unambiguous against the parallel protect_get_light tool. It does not explicitly name or contrast a sibling, so it falls just short of the top mark.

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 guidance is conditional paging advice ('On a large site, use limit and offset to page'), which is really parameter behavior rather than a when-to-use rule. It never states when to prefer this over protect_get_light, leaving the list-vs-single distinction to be inferred 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile requires no prose. The description does add one genuinely behavioral detail beyond that: paged results return totalCount and offset. However, the bulk of the remaining text is a field-by-field dump of the return payload, which the output schema already owns, and no auth/permission or freshness caveats are 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 opening sentence and the closing pagination sentence are tight and front-loaded, and the alarm-hub exclusion is correctly placed early. The long parenthetical enumeration of nested alarmHub/threadState fields is bulky and largely redundant given that an output schema exists, so not every 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?

For a two-parameter read-only list tool with a full output schema and complete schema descriptions, the description covers dataset scope, sibling routing, and pagination semantics — everything needed to call it correctly. It loses a point mainly for spending completeness budget restating return fields instead of, say, whether results are site/NVR-scoped.

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% (limit = 'Return at most this many items', offset = 'Skip this many items first'), so the schema fully documents both parameters and the baseline is 3. The description only repeats the paging intent and adds that paged output includes totalCount/offset, which is marginal added 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?

Specific verb (list) + resource (link stations), with an explicit scoping definition: 'non-alarm-hub gateways'. It names the sibling that handles the other case (protect_list_alarm_hubs) and identifies the single-item sibling implicitly. An agent can distinguish this from protect_list_alarm_hubs and protect_get_link_station without opening any schema.

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?

Gives an explicit when-not/alternative rule: alarm hubs belong to protect_list_alarm_hubs. It also states the condition for using the alternative invocation mode ('On a large site, use limit and offset to page'), so both the tool choice and the parameter choice are routed for the agent.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds behavior the annotations do not: the array return shape, the paging behavior on large sites, and the explicit gotcha that slots use a `cameras` string-array rather than a single `cameraId` — a real tripwire for callers.

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 one-line purpose, then richer detail, then the caveat and paging note; the ordering is sensible. It is somewhat dense, and the enumerated liveview fields partly duplicate the existing output schema, but nothing is truly wasteful.

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 annotations covering the safety profile, a full output schema, and 100% schema description coverage, the description supplies only the extra bits an agent actually needs: the definition of a liveview, the string-array slots gotcha, and paging/totalCount behavior. Nothing required to call or interpret the tool 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 100%, so limit/offset are already documented in the schema, but the description adds real semantics: that paging is the mechanism on large sites and that a paged response also carries totalCount and offset. That is genuinely new information about how the parameters behave.

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 all live views') and even defines what a live view is (camera grid layouts shown on viewers / in the Protect UI), which disambiguates it from unrelated Protect resources. It does not name or contrast the sibling protect_get_liveview, so the list-vs-single routing 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?

The paging advice ('On a large site, use limit and offset to page') is conditional usage guidance, but there is no explicit statement of when to use this tool versus protect_get_liveview or the other protect_list_* tools. Usage context is implied rather than 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?

Annotations already cover the read-only, non-destructive, closed-world safety profile, so the bar is lower. The description adds real context beyond structured fields: the single-object return behavior that contradicts the 'list' naming, which prevents a caller from misparsing the response.

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 followed by the important naming caveat. The trailing field enumeration is somewhat redundant given an output schema exists, but the overall text is compact and earns most of its space.

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 read tool with an output schema and clear annotations, the description covers everything needed to call it correctly. The return-field list duplicates the output schema rather than adding new information.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate.

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 ('NVR console info'). Critically, it resolves the naming ambiguity against the sibling list/get pattern by noting that despite the 'list' name, the endpoint returns a single NVR object, so an agent knows no separate get_nvr sibling exists.

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 - it is the only route to NVR info and the note discourages array expectations - but there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance. Adequate but with a clear 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered. The description adds the useful cross-reference that an output's id is the outputId for protect_activate_relay_output, but the bulk of the text enumerates return fields rather than behavioral traits.

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

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

Purpose is front-loaded, but the body is a dense run-on enumerating every nested field of the relay object. Since an output schema already exists, this field-by-field listing largely repeats structured data and hurts readability without adding proportionate value.

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

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

For a simple list tool with a full output schema, annotations, and 100% schema coverage, the description is more than adequate and even documents return structure beyond requirements. Nothing needed to call it correctly 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 100% and both parameters are documented, so the baseline is 3. The description goes beyond the schema by explaining how limit/offset behave together (paging) and that a paged response includes totalCount and offset, which the schema does not state.

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 all relays managed by UniFi Protect'), which cleanly separates it from the singular protect_get_relay sibling. The scope ('all relays managed by') is explicit, so an agent knows exactly what universe is returned.

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?

Gives a concrete operational condition ('On a large site, use limit and offset to page') and explains what a paged result returns. It stops short of naming alternatives (protect_get_relay / protect_subscribe_devices), so it is clear context rather than full when/when-not 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?

Annotations already declare readOnlyHint, openWorldHint=false, and destructiveHint=false. The description adds useful behavioral context by explaining pagination behavior and that a paged result returns totalCount and offset, though it does not cover auth or rate limits.

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 the purpose, but the middle is an extensive enumeration of return fields that is redundant given the existing output schema. This bloats the description and violates the principle that every sentence should 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?

Given the tool's simplicity, the annotations, the 100%-covered schema, and the existing output schema, the description supplies all necessary context: it identifies the resource, return type, and pagination mechanism. The extra field list is overcomplete but does not leave gaps.

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

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

Schema description coverage is 100%, so the schema already documents limit and offset. The description mentions using them to page but adds no syntax or semantic detail beyond what the schema provides.

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

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

States a specific verb ('List') and resource ('sensors managed by UniFi Protect'), clearly distinguishing it from siblings like protect_get_sensor and protect_list_cameras.

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 pagination guidance ('On a large site, use limit and offset to page') but does not explain when to choose this tool over protect_get_sensor or other list tools. Usage is implied rather than explicitly contrasted with alternatives.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety and side-effect behavior are covered. The description adds pagination behavior (totalCount/offset in paged results), which is genuinely useful, but repeats the return-field inventory that the output schema already provides instead of disclosing anything richer (e.g. whether an empty site 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 and paging advice are front-loaded and tight, but the long field-by-field inventory (id, modelKey, name, mac, state ... nested wirelessConnectionState sub-fields) is verbose and largely redundant with the output schema, adding bulk without adding selection value.

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

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

The tool's real complexity is pagination, and that is fully addressed; the presence of an output schema means return values need not be enumerated. The only gap is the absence of sibling routing guidance, which the agent would otherwise have to infer.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description goes further by explaining the behavioral consequence of the two parameters — that a paged result adds totalCount and offset to the response. That is meaning beyond the schema's 'return at most this many items' and 'skip this many items'.

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 all sirens managed by UniFi Protect'), which cleanly separates it from protect_get_siren. It does not explicitly contrast with siblings or the other protect_list_* tools, 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?

Gives one concrete usage condition — 'On a large site, use limit and offset to page' — which is real guidance, but it never states when to prefer this over protect_get_siren or the other list tools. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context in noting that paged results also return totalCount and offset, but the long field enumeration largely duplicates the existing 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?

Front-loaded with the core purpose, which is good, but the mid-sentence field dump (id, modelKey, name, mac, ...) plus the '(7.3.70 docs)' fragment is noisy and mostly redundant with the output schema. It earns its place less than the opening and closing sentences do.

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 field list is redundant rather than necessary, and annotations cover the safety profile, so the description only needs to establish purpose and paging behavior — which it does. It is complete enough for a simple read-only list tool, though it omits ordering/default behavior for the paged call.

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

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

Schema description coverage is 100%, so limit and offset are already documented in the schema; the baseline is 3. The description corroborates their paging purpose ('use limit and offset to page') but adds no defaults, ranges, or syntax beyond what the schema states.

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

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

States a specific verb+resource: 'List all speakers managed by UniFi Protect.' The list-vs-get distinction against sibling protect_get_speaker is clear from naming, but the description never explicitly differentiates itself from that sibling or from other protect_list_* 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 gives one concrete usage cue ('On a large site, use limit and offset to page'), which is real guidance. However, there is no when-not guidance and no mention of the alternative protect_get_speaker for fetching a single speaker, so routing guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the scope limitation that enrolled-credential detail (NFC cards, fingerprints) is NOT exposed, and that paged responses also carry totalCount and offset.

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 core purpose and scope definition, then return shape, then paging. Dense but every sentence carries information; the inline field enumeration and API-version parentheticals are slightly heavy but justified for a schema-verified contract.

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 enumerate return fields, but it does note the empty-string email for service accounts and the enrolled-credential limitation — the two things an agent would otherwise get wrong. The only real gap is not routing the agent away from protect_list_users.

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 documents both parameters fully (100% coverage), so the baseline is 3. The description earns above baseline by explaining the operational purpose of limit/offset (paging a large site) and that paging changes the response envelope to include totalCount and offset.

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 and goes further by defining what a ULP user is (UniFi Identity users with enrolled credentials), which implicitly separates this list from protect_list_users. However, it never names that sibling, so an agent choosing between the two lists still has to infer the distinction.

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

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

Gives one concrete usage condition — page with limit/offset on a large site — but offers no when-to-use vs alternatives guidance and does not mention protect_list_users or protect_get_ulp_user. Usage is implied by the definition rather than 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?

Annotations already establish this as a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), but the description goes further by enumerating the returned fields and, more valuably, explicitly listing what the Integration API does NOT expose (roles, permissions, login history, groups, notification settings). It also discloses the paging shape (totalCount, offset returned for paged results), which prevents futile calls.

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 is front-loaded, followed by returned fields, exclusions, then paging advice, so a reader can stop early. Most sentences earn their place, though the parenthetical '7.3.70-verified' provenance tag is slightly noise for an agent selecting a tool.

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

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

An output schema exists, so return shape need not be spelled out, yet the description still summarizes returned fields and explicit exclusions, plus paging semantics. The only meaningful gap is no routing guidance against the closely named sibling protect_list_ulp_users.

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

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

Schema description coverage is 100%, so both limit and offset are already fully documented, setting the baseline at 3. The description adds value by tying them to a concrete scenario ('on a large site') and explaining what paging changes in the response (totalCount, offset), which the schema alone does not convey.

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 all Protect users') and adds the scoping caveat that results are filtered by the API key's access permissions. However, with siblings like protect_list_ulp_users and protect_get_user in the set, it never distinguishes which user population or granularity it covers, leaving that disambiguation to the agent.

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 one concrete usage cue ('On a large site, use limit and offset to page'), which is real guidance, but there is no when-to-use vs when-not guidance relative to protect_list_ulp_users or protect_get_user. Usage is implied rather than 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description adds genuine behavioral context: paged responses also return totalCount and offset. The enumerated return fields are largely redundant with the existing output schema, which slightly dilutes the added value.

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, then return shape, then paging advice in a logical order with no filler sentences. The long field enumeration is the one part that costs more space than it earns, since an output schema already exists.

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

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

With an output schema present, the description need not explain return values, yet it still covers purpose and pagination behavior adequately. Nothing critical for calling a ReadOnly list endpoint is missing, though an explicit pointer to protect_get_viewer for single-item lookups would make it fully self-routing.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already defines limit and offset individually. The description adds meaning by framing both parameters as a coordinated paging mechanism and disclosing the paged-response fields (totalCount, offset), which the schema does not.

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 all viewers managed by UniFi Protect") and scopes it as the collection-level operation, which implicitly separates it from the sibling protect_get_viewer. It never names the single-viewer alternative explicitly, so it stops short of full sibling differentiation.

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 gives one concrete usage cue — "On a large site, use limit and offset to page" — which tells the agent when paging matters. However, there is no guidance on when to use this list tool rather than protect_get_viewer for an individual viewer, or on 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?

Beyond the readOnly/destructive/openWorld annotations, the description discloses the truncation limits (200 messages or 100,000 chars), the early-stop flag, the error-on-connect-failure case, the message envelope shape, and even documentation gaps. This is unusually rich behavioral context for a streaming 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-loaded with the core behavior and return shape, and every sentence carries information (return contract, truncation, error mode, message envelope, doc caveat, use, availability). It is dense and long, but little of it is filler.

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

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

For a one-parameter WebSocket subscription tool, the description covers the return contract, truncation, error behavior, message format, intended use, and platform availability. Even though an output schema exists, nothing an agent needs to invoke or interpret this call 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 description coverage is 100% and there is a single optional parameter. The description's '(1-30s)' merely restates the schema's minimum/maximum/default, adding no syntax or semantic detail beyond what the schema already provides. Baseline 3 applies.

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 precise verb+resource: 'Connect to the device update WebSocket and collect messages for a specified duration', and clarifies scope with 'Use to detect device state changes or newly adopted devices'. It is clearly a streaming/subscription tool, but it never names the obvious sibling protect_subscribe_events, so the agent must infer the distinction from the word 'device'.

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

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

It states a concrete use case ('detect device state changes or newly adopted devices') and a hard environment exclusion ('Not available over Cloud Connector (api.ui.com)'). However, it never routes the agent away from polling alternatives such as protect_list_cameras / protect_get_camera, so no explicit alternative is given.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing truncation caps (200 messages or 100,000 chars), the early-stop behavior with truncated=true, the error-on-no-message failure mode, the exact return shape, and a known documentation gap for event kinds. These are behavioral traits the annotations cannot express.

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 core action and return contract, then progressively layers truncation, error, message shape, and availability. Dense but every clause carries operational information; no filler sentences.

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

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

Even though an output schema exists, the description fully covers boundaries, failure modes, payload structure, and deployment constraints. An agent has everything needed to invoke it correctly and interpret the result without further inspection.

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 description repeats the 1-30s bound, but it adds real meaning by tying duration to the truncation caps — clarifying that listening may end early before duration elapses. That interplay is not derivable from the numeric bound alone, so it edges above the baseline 3.

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

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

States a specific verb and resource: connect to the Protect event WebSocket and collect messages, with the envelope explicitly defining the payload as modelKey 'event'. The 'events' scope distinguishes it from the many list/get siblings, but it never names protect_subscribe_devices, the closest alternative, so differentiation must be inferred.

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