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

Annotations only indicate non-read-only/non-idempotent/non-destructive, so the description carries the behavioral burden. It discloses session replacement, caching/reuse of the resulting session, and the critical single-use/30-second expiry nature of the 2FA code. No contradiction with 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?

Three sentences with the core behavior and main caveat front-loaded. Every clause adds information; no filler or repetition of schema/defaults.

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-optional-parameter auth tool with no output schema, this is complete: it states what the tool does, when it is and isn't needed, the 2FA constraints, and the session lifecycle. An agent can decide correctly whether to call it and how to pass the parameter.

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

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

The schema already documents totp at 100% coverage, including the pattern and omission rule. The description adds valuable extra semantics: the code is single-use, expires in about 30 seconds, and must be passed exactly once — details the schema cannot 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 action ('Force a fresh login to the console') with a clear side effect ('replacing any cached session'). Distinguishes itself from routine automatic re-authentication by explaining when this explicit login is actually needed (2FA).

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 says 'Normally unnecessary' and describes the server's automatic on-demand login and 401 re-authentication as the default path. Then gives the exact condition for using this tool: supplying a two-factor code that cannot be supplied unattended.

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

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

The description adds meaningful behavioral context beyond the annotations: it reveals that the session file is deleted, that the next call will re-authenticate, and that this action is not a lockout. This complements the idempotentHint and destructiveHint annotations without contradiction.

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 with no filler. The core action and effect come first, followed by practical use cases. Every phrase 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 one-parameter logout tool, the description fully covers behavior, side effects, and usage intent. Annotations and schema cover safety and state-change acknowledgement, so 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?

Schema description coverage is 100%, and the schema already documents the sole 'confirm' parameter as requiring an explicit true acknowledgement. The description adds no additional parameter-level detail, which is acceptable given the schema carries the full meaning.

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

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

The description clearly identifies the action ('Drop the cached session and delete the session file') and the resource (cached session/session file). It distinguishes this from auth_login and auth_status by focusing on clearing the session, making its purpose unambiguous.

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

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

The description gives explicit use cases: 'clear a session after changing accounts, or to remove the cookie from disk.' It also clarifies a non-effect ('does not lock anything out'). It does not explicitly contrast with sibling tools, but the when-to-use guidance is strong enough.

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

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

The description adds substantial behavior beyond the readOnlyHint annotation: it logs in and makes a real call by default, distinguishes live results from cached state, reports whether writes are enabled, and explains that absent tools indicate configuration issues rather than bugs. This is rich, honest behavioral disclosure.

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

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

The description is compact yet information-dense, with the core purpose front-loaded in the first sentence. Every sentence earns its place: behavior, outputs, failure mode, and usage guidance are all included without repetition or fluff.

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

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

For a single-parameter diagnostic tool with a readOnlyHint annotation and no output schema, the description is complete: it covers default behavior, configurable fast path, reported values, unconfigured setup steps, and when to call it first. Nothing essential 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%, so the schema already documents the single 'probe' parameter. The tool description reinforces the default behavior and hints at the fast cached path, but does not add significant meaning beyond the schema's own parameter description.

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 ('Check whether this server can actually reach your UniFi Protect console') and clearly distinguishes this from data-listing siblings by framing it as a connectivity/diagnostic tool. It also enumerates the reported fields, leaving no ambiguity about what the tool does.

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 explicit when-to-use guidance: run it when something is not working, and call it first when an expected tool is missing. It does not explicitly state when not to use it or name alternatives, but the diagnostic context is clear enough for an agent to select it correctly.

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 readOnlyHint annotation, the description states that it 'changes nothing' and explains its actual behavior as 'reports findings and names the tool that would fix each one'. This gives an accurate, non-contradictory picture of side effects and output semantics, adding value beyond the annotation.

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?

Every sentence carries distinct content: scope, finding categories, intended use, and read-only behavior. The key intent phrase is placed before the read-only clarification, and there is no redundancy or 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 parameters and only a readOnlyHint annotation, the description covers invocation, behavioral contract, and the nature of the result ('reports findings and names the tool that would fix each one'). It is sufficient for an agent to select and call the tool correctly without further documentation.

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

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

The input schema has zero properties, and the description explicitly confirms that no configuration is needed by stating it checks 'every camera and the console'. With zero parameters the baseline is 4; the description adds conceptual meaning by framing the tool as a whole-system scan rather than a targeted query.

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, 'Check', against a clear resource ('every camera and the console') and enumerates concrete problem categories such as gated-off detectors, cameras keeping no footage, and storage about to stop recording. It also explicitly identifies itself as the tool for 'are my camera settings correct', which distinguishes it from the sibling get/list/export tools.

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

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

The description gives an explicit intended-query mapping — 'This is the tool for "are my camera settings correct"' — which tells an agent when to select it. It does not enumerate exclusions or name alternative tools for the same job, but none of the sibling tools perform this cross-device consistency check, so the omission is minor.

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

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

The description discloses several behaviors beyond the readOnlyHint annotation: it always writes to disk, never returns video inline, grows tens of megabytes per minute, fails instead of exhausting memory when exceeding UNIFI_PROTECT_MAX_DOWNLOAD_BYTES, and may return nothing if the camera was not recording. This gives the agent concrete expectations and 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?

Three focused sentences, with the core action front-loaded and no filler. Each sentence earns its place by covering purpose, output/scale behavior, failure mode, and a practical prerequisite.

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 clearly explains what the tool returns (a file path), how large the output can get, when it fails, and a common reason for an empty result. Combined with the thorough input schema, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already documents parameter formats, defaults, and pitfalls (e.g., ISO 8601, relative expressions, not using Unix seconds). The tool description does not add additional parameter-level semantics beyond the schema, 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 names a specific verb ('Export'), resource ('recorded footage from one camera over a time range'), and output ('MP4 file on disk'). It distinguishes this tool from siblings like get_camera_snapshot by emphasizing video export to a file, not inline or still images.

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 clear context for when to use this tool: 'Always writes to a file and returns the path — video is never returned inline' implies this is the disk-export tool. It also advises checking the recording mode before interpreting an empty result. However, it does not explicitly name sibling alternatives or state when not to use 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, so the safety profile is covered. The description adss value beyonnd that by disclosing the payoff load size (8-15 KB) and inner composition (including live statistics) — info the agent needs to expect a heavy response. It does not mention auth/rate-limit context, but for a read-only get those are lower stakes.

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

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

Three sentences with no filler: purpose is front-loaded, the size warning follows, and the sibling routing closes. Each sentence earns its place and nothing is repeated from the 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 single-record get with one well-documented required parameter and a readOnly annotation, the description is complete. It compensates for the missing output schema by describing both the payload's contents and its approximate size, so an agent knows what to expect.

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

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

Schema coverage is 100%, so the schema already documents cameraId thoroughly, incluing its source (from list_cameras), format (24-char hex), and negative guidance (not name/MAC). The description itself adds no param-level detail; per baseline with high coverage, 3 is appropriate.

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

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

The description uses a specific verb and resource ('Get one camera's complete record') and immediately enumerates what it covers (encoder channels, zones, masks, OSD/LED, ISP tuning, live statistics). It is clearly differentiated from siblings, especially by naming 'every setting the console holds', which distinguishes it from unifi_protect_list_cameras' summary view and unifi_protect_get_camera_snapshot.'

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 explicit ruouting: 'Prefer unifi_protect_list_cameras nless you speccifically need a field it does not carry.' It also provides a cost sentiment ('large, roughly 8-15KB') that juustifies preferring the lighter alternative. No inference is required.

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

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

The description goes well beyond the sparse readOnlyHint=true annotation: it discloses the disk write and returned fields, the large context cost of inline mode, and the forced-fresh-capture behavior that prevents stale cached frames. The local disk write is a client-side side effect rather than a mutation of the Protect system, so it doesn't contradict readOnlyHint=true. This is exactly the kind of behavioral context an agent needs that 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?

Four sentences with the core action front-loaded, followed by mode guidance, cost warning, and the cache-freshness caveat — each sentence earns its place. The cost figure is unusually specific but directly shapes agent decision-making, so it's justified. Slightly longer than the tightest possible version, but nothing 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?

With no output schema and only readOnlyHint=true as annotation support, the description carries the full burden and covers the essentials: return fields, both output modes, cost implications, and the staleness pitfall. Minor gaps remain — no error-case behavior and no exact return JSON shape — but since it names the return fields explicitly and covers parameter interactions, it is sufficiently complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3 even with no description-side parameter info. The description adds value above that baseline: it quantifies the context cost of output="image", explains the multiplicative cost when highQuality is combined with output="image", and names the default savePath directory (UNIFI_PROTECT_SNAPSHOT_DIR). These cross-parameter interactions are not present in the schema.

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

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

The description opens with a specific verb+resource pair — 'Capture a still frame from a camera as it looks right now' — which both states the action and pins the tool to live capture. The phrase 'right now' plus the forced-fresh-capture note distinguishes it from siblings like get_event_thumbnail (historical frames) and export_video (video). The default return (path, size, content type) further disambiguates what the tool produces.

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 clear in-tool mode guidance: use output="image" only when a vision model must inspect the frame, choose output="file" by default, backed by a concrete cost range (300,000–700,000 context characters) as the decision driver. It does not explicitly name sibling alternatives for historical captures, but the 'as it looks right now' phrasing implies the live-capture context.

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

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

The readOnlyHint annotation already declares the operation is read-only, and the description's 'Get' verb is consistent. The description adds meaningful behavioral context about what the record contains and includes a caveat ('where the camera captured them'), setting expectations that metadata may be incomplete. No contradiction with 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?

The description is just two sentences with no filler. It front-loads the core purpose, expands with specific metadata examples, and ends with the crucial usage instruction. Every sentence earns its place.

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

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

For a simple one-parameter read-only getter with no output schema, the description adequately covers what the tool returns and where to obtain the required id. It does not describe the response structure or error behavior, but those are less critical given the tool's simplicity and the readOnly annotation.

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 eventId parameter already has a clear description. The tool description reinforces it by instructing the agent to use the id from unifi_protect_list_events, adding cross-tool context that helps the agent correctly source the parameter value.

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

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

The description states a specific verb and resource ('Get one event's full record') and explicitly distinguishes this tool from the search-like sibling by listing detection metadata the search results leave out (per-object tracking, detected zones, license plate text, vehicle attributes). An agent can clearly tell it apart from unifi_protect_list_events and other getters.

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 a direct usage pointer: 'Use the `id` from unifi_protect_list_events,' establishing the prerequisite and source of the required parameter. It also contrasts with 'search results,' implying this is the tool to use when the full record with detection metadata is needed. It does not explicitly enumerate exclusions, but the context is clear.

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

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

Beyond the readOnlyHint annotation, the description discloses several important behaviors: it writes to disk by default, can return inline instead, consumes significant context in image mode, returns 404 for missing thumbnails, and creates parent directories for savePath. This is rich and useful behavioral information.

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

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

The description is compact and front-loaded: purpose first, then output modes, then input source. Each sentence earns its place, and there is no redundant or vague wording.

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 adequately explains the return behavior: file path by default or inline image. It also covers error conditions, input provenance, and parameter options, making the tool fully understandable for correct invocation.

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

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

Schema coverage is 100%, and the description still adds value: it explains that eventId comes from list_events, that hasThumbnail: true indicates an image exists, that output=image costs significant context for vision models, and that savePath parent directories are created. These go beyond the raw schema descriptions.

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

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

The description clearly identifies the verb and resource: fetch the still image captured for a Protect event. It distinguishes this from event metadata and from sibling tools like get_camera_snapshot or get_event_thumbnails by specifying the event-triggered still frame.

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 clear context on when to use the tool: pass an event id from unifi_protect_list_events and prefer events with hasThumbnail: true. It also explains the output=image alternative for vision models. It does not explicitly name sibling alternatives or state when not to use them, but the usage context is strong.

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 readOnlyHint annotation, the description discloses token cost per image, a hard cap of 6, and the non-failing behavior for events without thumbnails. This is significant context that an agent needs to predict cost and handle partial results correctly.

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 main purpose and each subsequent sentence adds decision-relevant guidance: use case, sibling preference, cost/cap, and failure behavior. No sentence is wasted.

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

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

For a two-parameter read-only tool with no output schema, this description covers when to use it, how to select inputs, cost implications, and what happens when thumbnails are missing. Nothing essential is left 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 description coverage is 100%, so the input schema already documents both parameters, including the eventIds cap and the output enum. The description reinforces the cap and the inline-return intent but does not add substantial parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The first sentence states a specific verb and resource ('Fetch the still frames for SEVERAL events at once') and highlights that frames are returned inline. It also clearly distinguishes this batch tool from the singular unifi_protect_get_event_thumbnail sibling.

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

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

The description explicitly says to prefer this tool over calling unifi_protect_get_event_thumbnail repeatedly, and tells the agent to pick worthwhile events from unifi_protect_list_events instead of scanning a whole night. It also explains the key use case: identifying who or what was there when smart detection is unavailable.

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 the description adds valuable behavior beyond that: it explains that the Protect version reported matters because the server talks to a private API that Ubiquiti changes between releases, and that version mismatch is a first diagnostic for 404 errors. This is genuinely useful operational context not inferable from structured 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?

Three sentences, each earning its place: the first defines return content, the second gives usage timing, the third explains a critical troubleshooting link. Dense but clear, with the most actionable information up front.

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 no-parameter, read-only informational tool, the description fully covers its contents, when to call it, and why a specific returned field (Protect version) matters for subsequent operations. No output schema exists, but the enumerated list substitutes adequately.

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

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

The tool has zero parameters, so the schema is trivially complete and the description need not explain parameter semantics. The baseline of 4 applies because there is nothing the description must compensate for.

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

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

The description states a specific resource ('the console') and enumerates the exact data returned: model, Protect version, firmware, timezone, uptime, storage, and device type counts. This clearly distinguishes it from sibling tools like list_cameras or list_users by focusing on system-level overview rather than entity lists.

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

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

It explicitly recommends calling this tool 'first on an unfamiliar system,' which is strong situational guidance. It does not name alternatives or exclusions, but the tool is unique in scope among siblings, so no alternative is needed.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds important behavioral context by disclosing that the result is a summary, not the full console record. It also explains why this matters, which helps the agent set correct expectations about response size and scope.

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

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

The description is compact and front-loaded: the first sentence states the action and the exact output fields, and the second sentence adds the summary-vs-full distinction and sibling alternative. Every sentence earns its place without padding.

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 zero parameters and no output schema, the description provides sufficient context by listing the expected fields, clarifying the summary nature, and pointing to the sibling tool for fuller detail. Nothing essential for invoking this tool 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?

The input schema has no parameters, so the description is not required to explain parameter behavior. The zero-parameter baseline of 4 applies, and the description adds no conflicting or redundant parameter information.

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

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

The description uses a specific verb ('List every camera on the console') and enumerates the fields returned: id, name, connection state, recording mode, firmware, and capabilities. It also explicitly contrasts itself with unifi_protect_get_camera, making the tool's scope and differentiation clear.

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 states when to use this tool versus the alternative: it returns a summary rather than the full camera record, and explicitly directs the agent to use unifi_protect_get_camera when the full record for one camera is needed. This gives clear selection guidance.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, and the description adds that the result includes volume and paired doorbell cameras. However, it does not mention whether the response is an array, whether pagination applies, or any authentication requirements, so some behavioral detail remains implicit.

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

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

A single sentence that is front-loaded with the action and resource, followed by the relevant output details. Every word earns its place; there is no filler or redundant restatement of the tool name.

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-only list operation, the description is sufficient: it states what is listed, which fields are included, and the description is unambiguous given the sibling context. With no output schema, the description still conveys the essential return-value content without overcomplicating the tool.

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

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

The tool accepts zero parameters, so there is no parameter confusion and schema coverage is trivially complete. The description therefore does not need to explain argument semantics; the baseline for a zero-parameter tool is appropriate.

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

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

The description uses a specific verb 'List' and identifies the exact resource: UniFi Protect chimes. It also states the meaningful output fields (volume and paired doorbell cameras), which distinguishes it clearly from sibling list tools that target cameras, lights, sensors, or viewers.

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 resource scope is explicit: use this tool when you need chime information, not camera, light, sensor, or viewer data. It does not name alternative tools or provide when-not conditions, but the noun 'chimes' supplies clear context for 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 only declare readOnlyHint=true; the description carries the behavioral burden and succeeds. It discloses that result warnings must be checked before reporting counts, that a disabled detector returns zero matches rather than proving nothing happened, that times follow the console's local clock, and that results include the camera name to avoid a second lookup. This is exactly the kind of non-obvious behavior an agent needs to interpret results correctly.

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 longer than average but every sentence earns its place: purpose, use case, result-field convenience, timezone nuance, warning behavior, and filtering advice. It is front-loaded with the core action and structured so the most critical warning is set off in caps. The busy-system point is slightly redundant with the limit parameter description but still reinforces the needed behavior.

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 explains what results carry and warns about the most failure-prone interpretation, zero matches versus disabled detection. It also addresses timezone semantics and camera-name availability. The schema covers parameter detail, so an agent has enough context to invoke the tool and interpret its result correctly.

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

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

The schema already covers all parameters with detailed descriptions, enums, defaults, and constraints, so the baseline is 3. The description's mention of types, smartDetectTypes, and cameraIds adds strategic emphasis but no new parameter semantics beyond what the schema provides.

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

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

The description opens with a specific verb and resource: 'Search recorded events over any time range', then enumerates the event categories covered. It clearly positions this as the list/search tool for recorded events, distinguishing it from sibling tools like get_event, get_event_thumbnail, and export_video. The example use case 'what happened at the front door last night' removes any ambiguity about the tool's role.

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 a concrete use case and tells the agent to narrow with types, smartDetectTypes, and cameraIds, and to check warnings before reporting counts. It does not explicitly state when to prefer alternatives such as get_event or unifi_protect_get_event_thumbnail, but the context is clear enough for an agent to select this tool for broad historical queries.

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

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

With readOnlyHint=true, the safety profile is already covered by annotations. The description adds useful behavioral context by specifying exactly which floodlight attributes are exposed, including connection state, on/off state, PIR motion detection, and brightness. It does not go into response envelope or error semantics, but for a simple list operation this is adequate.

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

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

A single sentence that starts with the verb and object, then lists the four key output attributes without filler. Every element adds information needed to select and use 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 no-parameter, read-only listing operation, the description is complete: it identifies the resource, the type of operation, and the meaningful data fields in the result. There is no output schema, but the description supplies the essential return semantics that an agent needs.

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

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

The tool has zero parameters and the schema has no properties, so there are no parameters to document. With 0 params the baseline is 4; the description appropriately focuses on what the list returns rather than on parameter explanations.

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 ('List') and clear resource ('UniFi Protect floodlights'), and explicitly enumerates the data returned: connection state, light-on status, PIR motion detection, and brightness. This cleanly distinguishes it from sibling listing tools for cameras, sensors, chimes, viewers, and liveviews.

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

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

The description implies the tool is for retrieving floodlight status/results, which is a clear selection context among the sibling tools. It does not name alternative tools or explicitly state when not to use it, but the resource-specific wording leaves little ambiguity for an agent matching intent to 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?

readOnlyHint=true already establishes the read-only safety profile. The description adds useful behavioral context by explaining that live views are named grid layouts and that the returned id serves a specific purpose in unifi_protect_update_viewer, going beyond the annotation without contradicting it.

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

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

Two sentences with no filler: the first states the action and defines the resource, the second explains why the return value matters. Information is front-loaded and 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 zero-parameter, read-only list tool with no output schema, the description covers what the tool does, what its domain term means, and what the returned id will be used for. No essential detail an agent needs to invoke this tool 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?

The input schema has zero parameters, so there are no parameter semantics for the description to add; per the 0-param baseline this is adequately handled. The description's mention of the returned id is output-focused, not parameter-focused, and doesn't need to compensate for any schema gap.

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

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

The description uses a specific verb ('List') and a specific resource ('saved live views'), and defines the term as 'named camera grid layouts shown on viewers and in the Protect app.' This clearly separates it from sibling list tools like list_viewers and list_cameras, and the second sentence connects the output to a downstream tool.

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

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

It states that the returned id is exactly what unifi_protect_update_viewer needs to place a layout on a screen, which gives a clear calling context. It does not explicitly name alternatives or when not to use the tool, but the downstream reference is sufficient for a list-with-no-filters 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?

The annotations already provide readOnlyHint=true, so the description does not need to restate safety. The added note that there is no start/stop tool and the pointer to unifi_protect_list_ptz_presets gives behavioral context beyond the annotation by warning agents not to search for a mutating patrol control.

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

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

The description is two short sentences with no filler. The purpose is front-loaded, and the second sentence adds a relevant cross-reference rather than empty prose.

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 one-parameter, read-only list operation, the description is complete enough: it names the resource, implies the required camera identifier, and routes around a nonexistent start/stop operation. The absent output schema is acceptable because the 'List' verb makes the return shape inferable and the annotations/schema cover the rest.

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 only parameter, cameraId, is fully documented in the schema with a precise explanation of where to find it, its format, and what it is not. The tool description adds no param-specific detail, but with 100% schema coverage the schema already carries that burden.

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 opens with a specific verb ('List') and a concrete resource ('a PTZ camera's saved patrol routes'), so an agent immediately knows what the tool does. It also references unifi_protect_list_ptz_presets, which helps distinguish patrol routes from presets and explains the absence of a start/stop operation.

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 states the action: list saved patrol routes for a PTZ camera. The cross-reference to unifi_protect_list_ptz_presets signals that an agent should look there to understand why start/stop tools do not exist, providing useful context for selecting among related tools.

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

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

Annotations provide readOnlyHint=true, and the description adds substantial context beyond that: this server wraps a private API, the official Integration API (separate X-API-KEY auth) is out of scope, and preset creation/driving happens in the Protect app. This prevents an agent from attempting write-style PTZ operations that would fail.

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 core purpose is front-loaded in sentence one, and each of the three sentences carries distinct value. The final sentence is dense, packing the API-scope and no-movement caveats with a colon, parenthetical, and em-dash, and could be split into two sentences without losing 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 single-parameter read-only list tool with a fully documented schema, the description is nearly complete: it states return content, applicability condition, and surrounding API constraints. The only gap is unspecified behavior when given a non-PTZ camera (empty list vs. error), which is minor.

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% — the cameraId property already documents that it must be the 24-character hex id from unifi_protect_list_cameras, not the name or MAC. The tool description adds no parameter details, 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 — lists a PTZ camera's saved preset positions plus the slot number each occupies. It differentiates from siblings by tying meaning to hasPtz: true and implicitly distinguishing presets from patrols (unifi_protect_list_ptz_patrols is a sibling).

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 conditions usage on cameras reporting hasPtz: true in unifi_protect_list_cameras, telling the agent which precondition to check first. It also names what NOT to attempt — moving the camera or running a patrol — and explains those operations exist only on Ubiquiti's official Integration API with separate auth, routing the agent away from a dead end.

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 readOnlyHint annotation already signals a safe read, and the description adds meaningful behavioral context by explaining that readings are extracted from the console's per-metric history arrays rather than returning the full raw arrays. This helps the agent anticipate a compact, filtered response and understand why the tool behaves that way.

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

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

The description is two sentences with no wasted words: the first states the operation and output, the second gives a useful implementation detail. It is front-loaded with the most important information and remains compact.

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

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

For a parameterless listing tool with no output schema, the description fully specifies the returned data categories and even the data source and transformation behavior. An agent has everything needed to select and invoke the tool correctly.

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

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

There are no parameters, so the schema requires no explanation. The description adds nothing beyond the schema, but with zero parameters this is not a gap; the baseline of 4 is appropriate.

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

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

The description names a specific verb and resource, 'List UniFi Protect sensors', and immediately differentiates the tool from sibling list tools by enumerating the sensor-specific readings it returns. Even without an explicit sibling comparison, no agent could confuse this with list_cameras or list_lights.

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 makes the use case clear: call this when you need current sensor readings and states such state such as temperature, humidity, light, open/closed, motion, and battery. It does not explicitly name alternatives or exclusion conditions, but no sibling tool covers sensors, so the context is sufficient.

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

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

The annotation readOnlyHint: true already declares the operation safe, so the description does not need to restate that. The description adds useful context about the returned data (role, last login), but does not disclose any additional behavioral details such as ordering, pagination, authentication requirements, or error behavior. It does not contradict the annotation.

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 carry all the essential information: what the tool does and why an agent would use it. There is no repetition of the tool name or schema, and the primary function is front-loaded.

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

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

For a zero-parameter read-only list tool, the description is sufficient for an agent to select and invoke it correctly. It names the resource, the key output fields, and the intended use case. With no output schema present, the description adequately conveys what the agent should expect.

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

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

The tool has zero parameters, so parameter-level elaboration is unnecessary. The schema coverage is effectively complete with no properties to document, and the description adds no parameter semantics because none are needed.

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

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

The description uses a specific verb ('List') with a clear resource ('accounts that can sign in to Protect') and adds detail about what is returned (role and last login). It clearly distinguishes this from the camera/event/liveview listing siblings by focusing on user accounts and access auditing.

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 a clear use case: 'Useful for auditing who has access to the cameras.' This tells the agent when to choose this tool, but it does not explicitly name alternatives or state exclusions. For a simple zero-parameter listing tool, this is sufficient but not maximally 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?

The readOnlyHint annotation already covers the safety profile, so the description's job is to add context beyond it. It does add value by disclosing the return content (device list plus current live view per device). However, it doesn't mention whether offline/unadopted devices are included or whether authentication is required. No contradiction with 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?

A single sentence with zero waste. The verb, resource, and output detail are all front-loaded in natural reading order. Every word 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 zero-parameter, read-only listing tool, the description is nearly complete: it names the resource and the key output attribute. No output schema exists, but the description adequately communicates what the agent will receive. Minor gaps like pagination, ordering, and handling of offline devices prevent a 5, though these are low-stakes for a simple list operation.

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

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

The tool has zero parameters and 100% schema coverage, so the schema is trivially complete. The description need not explain parameters, and it correctly doesn't. Baseline 4 for zero-parameter tools is appropriate.

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

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

The description states a specific verb ('List'), a specific resource ('UniFi Protect Viewport devices'), and a distinctive output detail ('which live view each is currently displaying'). This distinguishes it from siblings like list_cameras, list_users, and list_liveviews, since it targets Viewport hardware rather than the live views themselves.

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

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

No explicit when-to-use or when-not-to-use guidance is provided, and no alternative tools are named. However, the usage is reasonably implied by the precise name and description: use this when you need informmation about Viewport devices and their currently assigned live view. The distinction from list_liveviews is left for the agent to infer 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 readOnlyHint=true align with the description's 'only GET is permitted'. The description adds important extra behavior not in annotations: responses are returned raw and unshaped, can be hundreds of kilobytes, and writes can be enabled via UNIFI_PROTECT_ALLOW_WRITES=1. This is exactly the kind of context agents need. No contradiction with 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?

The description is front-loaded with the 'escape hatch' framing, then explains rationale, warns about raw responses, and states write restrictions. Each sentence earns its place; slightly long but justified for an undocumented endpooint escape hatch.

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?

Despite no output schema, the description covers return behavior, size caveats, write restrictions, and the conditional override. Combined with a fully described schema, an agent has enough to call and interpret this 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 the schema already documents path, query, body, and method. The description itself does not add parameter-level details, but it does clarify the write-disabled context and raw response behavior. 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 clearly states a specific purpose: directly call any private Protect API endpoint relative to /proxy/protect/api. It differentiates from the wrapped sibling tools by framing itself as an 'escape hatch' and explicitly says 'prefer the wrapped tools, which summarize.'

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 provides explicit when-to-use: when a wrapped tool starts returning 404 because Ubiquiti moved an endpoint. It also tells the agent to prefer wrapped tools and warns against broad endpoints like bootstrap. This is strong routing guidance relative to the siblings.

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