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

The description goes far beyond the readOnlyHint annotation by explaining the audit algorithm, the cohort bucketing, the '<CAM>' path templating to avoid false positives, and the separate 'disabled_outliers' reporting. It also warns that outliers are not necessarily bugs and clarifies that there is no live BI connection. This is rich behavioral disclosure with no contradiction against 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 long but each sentence earns its place: purpose, methodology, false-positive avoidance, output organization, and user-handling guidance are all useful. It is front-loaded with the core purpose and only then dives into mechanics. Slight redundancy around 'informational' and 'pure read' is minor.

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?

There is no output schema, so the description carries the burden of explaining return behavior; it names the output keys ('outliers', 'disabled_outliers', 'unbucketed') and clarifies how outliers should be interpreted. It also covers the tool's read-only nature, the data source, and appropriate user interaction. No critical operational detail appears to be missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds general context about cohorts and modal values, which relates conceptually to min_cohort, but it does not add parameter-level meaning beyond what the schema already provides. This is adequate given the schema already documents each parameter.

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

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

The description opens with a precise verb and resource: 'surfaces cross-camera action-row outliers' by walking each camera's .reg export and bucketing action rows into cohorts. It clearly identifies what the tool does and why, and the mechanics distinguish it from simple getter tools like bi_get_actionset or bi_list_alerts. It is not a tautology and states a specific analytical purpose.

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 context for when to use the tool: when the user needs to review cross-camera action-row divergences, and it explicitly instructs the agent to present findings as 'values worth confirming' and ask whether each is intentional. It does not explicitly name alternative tools or list exclusion criteria, but the use case is clearly scoped as an informational audit rather than a live query.

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, so the bar for extra disclosure is lower. The description adds meaningful behavioral context beyond that: it returns raw facts for simple matches and leaves verdicts to the caller, it cross-references a ±2-minute log window, and it is Admin-gated via the log cmd. It does not contradict the readOnlyHint, and the only minor gap is the absence of explicit failure behavior, but the added context is strong.

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

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

The description is a single dense paragraph but front-loads the key usage ('Use after bi_list_alerts') and continues with concrete details in order of importance. It earns its length by explaining complex return semantics and an important cost wrinkle. It is longer than minimal, but for a tool with this analytical complexity, the length is justified; a small structural improvement would be bullet points, so not a perfect 5.

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 lacking an output schema, the description covers what the tool returns, how to use it, the interpretation policy for simple matches, the time window of the log cross-reference, and the cost/privilege caveat. For a tool this complex, the description is unusually complete: an agent could decide to call it without needing to open the schema, and would know what to do with the response.

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 all four parameters. The description adds value by clarifying that 'path' comes specifically from bi_list_alerts and noting the cost trade-off for max_alert_age_h. It connects parameters to real usage, going slightly beyond bare schema entries, though it could have precisely linked 'camera' and 'path' examples to the decoded output.

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 tool as an alert-chain explainer that decodes what actions fired on a specific alert, with a specific verb ('explain'), a specific resource (alert action chain), and a concrete workflow context ('Use after bi_list_alerts'). It distinguishes itself from siblings by emphasizing decoded filters, comparator verdicts, and log cross-referencing, which none of the sibling names or descriptions suggest.

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 states when to use it: after bi_list_alerts, and exactly what to pass: the alert's path from that response. It also gives a clear exclusion for simple filter matches (caller decides FIRED vs SUPPRESSED) and a warning about admin-gating and log cost for older alerts. This is actionable guidance with no ambiguity.

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

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

Beyond the readOnlyHint annotation, the description discloses detailed decoding behavior, unmapped-value fallthrough with raw ints preserved, and a staleness caveat tied to .reg export source. This gives the agent an accurate model of what the call will and won't reflect.

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 dense sentences, each earning its place: purpose, decoding detail, fallback behavior, and data-source caveat. The main purpose is front-loaded, and no content is redundant with 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 complex read-only decoder with no output schema, the description is complete: it names the decoded fields, bitmask groups, raw fallbacks, and the source/staleness limitation. An agent has enough context 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the shaped-output contents and raw fallthrough, which clarifies the meaning of the raw flag, and by enumerating hook-related fields (OnTrigger/OnReset) that map to the hook parameter.

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

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

The description opens with a specific verb and resource: 'Return the semantic action set (OnTrigger and/or OnReset) for a camera.' This precisely identifies the tool's function and distinguishes it from sibling getters that target alerts, clips, config, or PTZ status.

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 purpose is unambiguous, and the caveat about .reg export data implies it is for inspecting exported action sets rather than live UI state. However, it never names an alternative tool or explicitly states when not to use it, so it falls short of full routing guidance.

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

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

The readOnlyHint annotation merely indicates a safe read; the description adds substantial behavioral detail: it returns the most-recent alert at-or-before 'at', returns base64 plus record/time/memo, resolves internally via alertlist and /alerts/@record, and ignores w/h/scale params. It also explains the markup source-vs-bug distinction and the low-resolution thumbnail issue, so the agent can anticipate real-world 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 description is long but every sentence earns its place: core behavior is front-loaded, followed by the time-resolution rule, the live-frame exclusion, the markup caveat, and the distinct low-resolution issue. The structure moves from primary use to edge cases without redundancy, which is appropriate for a tool with nuanced 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?

The tool has no output schema and complex semantics, yet the description covers what is returned, how time resolution works, how markup behaves, what endpoint it uses, and likely misdiagnoses. Even the raw parameter, while not explained in description, is sufficiently documented in the schema, so 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?

Even with 100% schema coverage, the description adds meaning beyond the schema: it explains that 'at' resolves to the most-recent alert at-or-before that time, that omitting it fetches the latest alert, that 'markup' only produces a box when BI stored a detection score, and that 'camera' must be a specific camera, not 'Index'. These are semantics 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?

The description states a specific verb and resource: 'Fetch the STORED alert image' for a camera, resolved by time. It also explicitly differentiates from bi_get_camera_snapshot, telling the agent this is not a live frame but the frame BI saved when an alert fired.

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 invocation guidance: pass 'camera' with optional 'at', omit 'at' for the most recent alert, and use a specific camera rather than 'Index'. It names the alternative tool for live snapshots and explains when to use that instead, plus how markup behavior should be interpreted.

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 readOnlyHint annotation by disclosing that the tool is known broken on a specific version, that both read and admin paths return 'Access denied', that the gating mechanism is undocumented, and that it falls back between clients accordingly.

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 and the warnings are relevant, but the explanation is somewhat lengthy due to repeated broken-state warnings and speculative admin-client reasoning. Still, most sentences add necessary context.

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 tool with no output schema, the description covers the input source, current known-broken behavior, authentication path behavior, and the practical instruction not to depend on it. Nothing essential for correct use 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 the baseline is 3. The description adds meaningful provenance for the required 'path' parameter by pointing to bi_list_alerts as the source, which is not evident from the schema alone.

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

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

The description states precisely what the tool does: returns AI object tracks (per-frame bounding boxes) inside one alert. This clearly distinguishes it from sibling tools like bi_get_alert_image or bi_list_alerts by naming the resource and scope.

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 concrete prerequisite: pass the alert's 'path' from bi_list_alerts. It also warns not to rely on the tool until gating is characterized, but it does not explicitly name alternatives or enumerate when to prefer this over sibling tools.

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

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

Beyond the readOnlyHint annotation, the description discloses authentication-dependent behavior, what each call path returns, and which fields are intentionally absent from the API. This prevents the agent from expecting unsupported data and fully explains the tool's actual 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?

Three dense sentences with no filler. The core purpose is front-loaded, the conditional behavior is explained compactly, and the limitation/alternative is placed at the end where it matters. 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?

Despite no output schema, the description adequately communicates the returned fields, the auth-dependent behavior, and the boundary of what is not available. For a read-only config retrieval tool, this is sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100%, so both 'short' and 'raw' are already documented clearly. The description adds some context by mentioning the shaped vs raw distinction indirectly, but it does not need to compensate for schema gaps, so a baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as returning per-camera configuration and state, enumerates the specific data fields (motion sensitivity, AI zones, recording mode, stream paths, schedule/profile flags), and explicitly names what it does not expose. This differentiates it from siblings like bi_get_reg and bi_get_camera_motion_config.

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 explicit usage context: admin credentials trigger one call path, non-admin falls back to another. It also names an alternative tool (bi_get_reg) for data this tool cannot return, which directly guides an agent's tool selection.

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

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

Annotations provide readOnlyHint=true, and the description reinforces this by explaining the tool is read-only by design and that the camconfig set-half is a silent no-op in 5.9.9.71. It also discloses admin-required access, stale-reg avoidance, and the exact return structure. No contradiction with annotations; a strong behavioral disclosure overall.

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 dense but information-rich, front-loading the core purpose and then delivering precise exclusions and edge-case behavior. It earns its length by distinguishing this sibling-heavy tool from nearby alternatives and naming specific return keys, though it could be marginally trimmed without losing meaning.

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, two-parameter tool with no output schema, the description provides a good picture of return shape and key limitations. It tells the agent the admin requirement, the no-op caveat, what is NOT included, and where to get AI thresholds and zone polygons. The only minor gap is the absence of the camera short-name discovery path, but that is already handled by the required parameter and sibling tools.

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 both parameters (short and raw are documented there). The description doesn't dwell on parameters, but it adds useful context for what the raw flag returns (verbatim motion_raw/post_raw twins), which complements the schema without needing to repeat it.

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

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

The description clearly states that the tool reads live motion and post-trigger settings from BI's admin camconfig cmd, explicitly distinguishing it from bi_get_reg(key_path='Motion'). It also enumerates the returned fields (motion, post, motion_raw, post_raw), so an agent can confidently identify the tool's purpose and scope.

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 use this tool instead of bi_get_reg(key_path='Motion') when tuning sensitivity/contrast/breaktime to avoid stale .reg exports, and explicitly directs AI threshold queries to bi_get_reg(key_path='AI\<n>'), noting trigger-zone polygons remain in bi_get_reg. This gives clear when-to-use and when-not-to-use guidance.

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

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

The readOnlyHint annotation already signals safety; the description adds the base64 return format and clarifies that the agent, not the tool, is responsible for writing to disk. This goes beyond the annotation without describing every failure mode.

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 tightly written sentences lead with the operation and endpoint, then cover output format and use cases. Every phrase adds value and there is no repetition of schema content.

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 action with no output schema, the description explains the HTTP endpoint, the return encoding (base64), the side-effect behavior, and intended use cases. The agent has enough information 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%, so the schema already documents 'camera' and 'raw'. The description only reinforces the camera short name through the endpoint template, adding no meaningful semantic information beyond the schema.

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

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

The description names a concrete verb ('Fetch'), a specific resource ('a single current JPEG frame from a camera'), and the underlying endpoint, making it easy to distinguish from alert/clip-based siblings like bi_get_alert_image.

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?

Three concrete use cases are given (live-coverage cross-referencing, PTZ preset verification, still capture) and it explicitly frames the tool as an alternative to the alert/clip pipeline. It does not name sibling tools directly, but the guidance is clear enough for an agent to know when to call 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 adds meaningful behavioral detail about the trigger-time snapshot (AI/profile/schedule/zones), going beyond what the schema alone provides. No contradiction exists.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the path-source instruction is placed exactly where it is needed.

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 tool with two parameters and no output schema, the description provides enough context: what data is returned and where the input comes from. The exact shaped output format is not described, but the listed fields and raw option cover the main use cases.

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 both parameters well. The description adds extra value by clarifying that 'path' must come from bi_list_alerts and by implying the shaped view behavior of the tool.

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

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

The verb 'get' is paired with a specific resource ('one clip/alert') and a concrete list of returned fields (resolution, duration, AI/profile/schedule/zones active at trigger time). This makes it easy to distinguish from siblings like bi_list_alerts or bi_get_alert_tracks.

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 tells the agent to pass the clip 'path' from bi_list_alerts, which is a clear usage instruction tied to a sibling tool. It does not enumerate exclusions or when to prefer an alternative, but the context is sufficient for correct selection.

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

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

Annotations already indicate readOnlyHint=true, and the description adds rich behavioral detail: all BI fields are passed through, two derived helpers are added, preset_map indexing and filtering behavior is explained, and active_preset is conditionally present. This goes well beyond the annotations and clearly shapes agent expectations.

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 a one-sentence purpose, then compactly lists pass-through fields and explains derived helpers and prerequisites. Every sentence adds necessary information and there is no filler or redundancy.

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

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

With no output schema, the description carries the full burden of explaining return data. It enumerates the pass-through fields, describes both derived helpers in detail, covers edge cases like undefined/empty descriptions, and states the required camera condition. Together with the schema, an agent has enough to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the input schema already fully documents both parameters. The description adds only the PTZ-enabled prerequisite relevant to the camera parameter and does not meaningfully expand on the raw parameter, leaving the baseline at 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?

The description clearly states the operation: retrieving PTZ state for one camera. It also distinguishes this from sibling camera-related tools by emphasizing PTZ-specific fields and derived helpers, making the tool's scope 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 clear context for when to use the tool: to get PTZ state for a single camera. It also provides a key prerequisite, 'Camera must have PTZ enabled in BI,' which guides proper usage. It does not explicitly name alternatives or exclusion conditions, but the PTZ-focused purpose is clear 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?

With readOnlyHint=true already disclosing safety, the description adds meaningful behavior: it parses a .reg export, optionally limits to a subtree, and returns a staleness warning when the file is older than 7 days. No trait contradicts 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?

Three dense sentences carry purpose, use cases, optional parameter behavior, and a warning with no filler. The most important scoping statement is front-loaded, and every clause contributes.

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?

There is no output schema, but the description sufficiently indicates the return value (requested key subtree) and the staleness warning, while the raw parameter explains shaped vs raw output. A little more about failure or invalid key_path behavior would make it fully complete, but an agent can correctly call it from this description.

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 camera, raw, key_path, and include_masks. The description only repeats the key_path limiting example and adds no 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?

Description opens with a specific verb and resource: 'Parse a camera's .reg export and return the requested key subtree.' It then explicitly frames the tool as covering what 'the BI JSON API does NOT expose', which differentiates it from the sibling getters without requiring schema inspection.

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 clear when-to-use guidance by naming concrete use cases (trigger zone polygons, AI confidence thresholds, per-preset alert-skip flags, ONVIF handlers, alert actions) and positions the tool against the JSON API. It stops short of naming a specific alternative or stating when not to use it, but the context is unambiguous.

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, covering the safety profile. The description adds useful context about what data is fetched, such as current user capabilities and available profiles, but it does not disclose other behavioral traits like authentication requirements or the distinction between the shaped and raw responses.

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

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

The description is a single, dense sentence that lists the returned data categories without any filler. It is front-loaded and every phrase adds value.

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

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

For a read-only tool with zero required parameters and no output schema, the description gives a reasonable outline of the return contents, which helps an agent understand what to expect. It does not specify the exact response structure, but that is a minor gap for this simple, optional-parameter tool.

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

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

Input schema coverage is 100%, and the single parameter 'raw' is already fully documented in the schema. The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the resource—BI session information—by enumerating its contents: version/license, timezone, user capabilities, and profile/schedule/stream names. It differentiates this tool from siblings through that content list. However, it lacks an explicit verb like 'get' or 'returns', relying on the tool name and title for that.

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 this tool is for fetching session-level metadata, but it gives no explicit guidance on when to use it versus siblings such as bi_get_sysconfig or bi_get_status. No alternatives, exclusions, or preconditions are mentioned, leaving the agent to infer usage from the listed contents.

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 declare readOnlyHint=true, and the description's 'Snapshot' wording is consistent with a read-only operation. It adds context about the specific state fields covered, but beyond that it does not disclose additional behavioral traits such as response formatting, raw vs. shaped output, or potential delays. This is acceptable given the read-only 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?

A single, compact sentence with a colon-separated list of state elements. It is front-loaded with the primary purpose and every listed item adds useful specificity without wasted words.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description provides a solid overview of the return content. It falls slightly short of full completeness because it does not mention the raw/toggle behavior or the overall output structure, but the schema covers the parameter and the field list gives adequate context.

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

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

Schema description coverage is 100%, with the sole raw parameter fully described as toggling between raw and shaped view. The description does not discuss this parameter, but the baseline of 3 applies because the schema already carries the semantic weight.

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 tool as retrieving a snapshot of Blue Iris system state and enumerates the specific components (active profile, CPU%, RAM, disk usage, etc.). This distinguishes it from configuration-focused siblings like bi_get_sysconfig, though it does not name an alternative tool directly.

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 guidance is provided. There is no mention of when this should be preferred over sibling getters such as bi_get_sysconfig or bi_get_session, and no exclusions or prerequisites are stated. The usage context is only implied by the tool name and field list.

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 an important behavioral detail: admin permission is required. It also discloses that it may expose DIO/MQTT state inline, which tells the agent the output can contain more than the named fields. 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?

Two sentences, front-loaded with the core purpose and admin requirement, then a precise usage direction. Every clause contributes information: the config items enumerated, the DIO/MQTT note, and the 'instead of screenshot' 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?

For a single-optional-parameter read tool with full schema coverage and a readOnly annotation, the description covers what the tool returns, who can use it, and when to prefer it. No output schema exists, so the inline DIO/MQTT note helps set expectations without over-specifying.

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 covers the single 'raw' parameter at 100%, so the baseline is 3. The description's 'shaped view' language meaningfully elaborates the default return format, adding context beyond the schema's generic boolean 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?

Description names a specific verb and resource: 'Get BI system config' with a concrete snapshot listing (FTP archive enable, global schedule, manual record time limit). It also signals admin requirement, which distinguishes it from read tools that don't need elevated access.

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?

States 'Use this instead of asking the user to screenshot Settings → Other,' giving a clear when-to-use instruction. It lacks explicit exclusions (e.g., when not to use it), but it provides enough context about its unique purpose among the large sibling set.

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 adds meaningful behavior beyond the annotation: omitted bounds default to the last 24 hours, and a rangeless query returns empty spans. This helps an agent predict response behavior for edge-case invocations.

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: purpose is front-loaded, and the second sentence delivers the key default/edge-case behavior. Every clause earns its place, and the description stays compact despite covering an important behavioral nuance.

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 tool with five well-documented parameters and no output schema, the description alongside the schema is largely sufficient: required parameter, default time window, and rangeless edge behavior are all stated. The return structure is only hinted at via 'buckets' and the raw-vs-shaped distinction, but nothing critical for a 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 description coverage is 100%, so the schema already documents all five parameters. The description mostly restates the camera requirement and the default-window behavior already present in the startdate/enddate schema descriptions. It adds little semantic value beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly identifies a camera-specific activity timeline with motion/trigger/alert buckets, and the tool name supplies the 'get' verb. This is readily distinguishable from sibling tools like bi_list_alerts or bi_get_clip_info because it returns an aggregated timeline rather than individual alerts or clips. The '24-hour' phrasing is slightly tied to the default window, but the second sentence resolves that ambiguity.

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 use case—querying camera activity over a time window—but never explicitly states when to choose this over sibling tools such as bi_list_alerts or bi_get_camera_snapshot. It provides useful parameter-level guidance about startdate/enddate defaults and rangeless queries, but not tool-selection guidance, so usage context 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 provide readOnlyHint=true, and the description adds meaningful behavioral detail beyond that: no dedup, per-alert timestamps and memos, flexible date format parsing, default limit, and the important flagged-view crossover where clip items lack 'zones' and 'msec' means clip length instead of alert length. This exceeds what annotations alone communicate.

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 dense but well-organized: front-loaded output summary, then usage guidance, then parameter formats, then the critical crossover edge case. Every sentence contributes distinct information, and it links to the schema for the full view enum rather than duplicating it.

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 7-parameter list tool with no output schema, the description covers the essential operational context: what is returned, when to use it, date formats, filters, default limit, and an important view-related anomaly. A small gap is the lack of explicit response shape or ordering/pagination behavior, but the high schema coverage and readOnly annotation reduce the need for 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by specifying the accepted formats for startdate/enddate (unix epoch int, ISO-8601, relative shorthand with examples), explaining that 'search' is a server-side memo substring, noting the 'Index' sentinel for camera, and giving the default for 'limit'. It does not redundantly restate every schema property.

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

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

The description uses a specific verb-resource combination ('Recent alerts...') and clearly states what the tool returns: AI memo (object, confidence, license plate), zones triggered, and clip path. It also distinguishes itself from nearby siblings by naming bi_list_log as the alternative to use after this tool and by calling itself the 'First stop' for alert-chain reconstruction.

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 says when to use this tool ('First stop for what fired when / reconstructing an alert chain') and when to prefer another ('Use this before bi_list_log when investigating a specific event'). The crossover note about 'flagged' view potentially returning clip items also warns the agent about a case that would otherwise look like a different tool's domain.

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, so the safety profile is covered. The description adds useful content detail about what the list contains, but discloses no behavioral traits such as whether listing 'all cameras' triggers per-camera live queries, how groups are represented, or how the shaped view differs from the raw payload. No contradiction with the read-only 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?

The entire description is one dense sentence with no filler; the scope ('List of all cameras and groups') is front-loaded and every clause adds a specific field detail. Nothing could be trimmed 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?

With no output schema present, the description's field enumeration is the agent's only view of the return shape, and it is reasonably informative. However, it doesn't explain how groups appear in the list, how the limit interacts with groups, or what distinguishes the shaped view from the raw one beyond the parameter description.

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 both 'raw' and 'limit' already documented in the input schema. The description adds no parameter-level meaning beyond what the schema provides, 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 ('List'), the resource ('all cameras and groups'), and enumerates the exact returned fields: online state, motion/trigger/alert counts, stream bitrate/FPS/resolution, last alert time, and error state. This clearly positions the tool as a status-overview listing rather than a config or snapshot tool. It doesn't explicitly contrast with any sibling, and the 'groups' inclusion is stated but not defined, which keeps it from a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as bi_get_status or bi_get_camera_config, and no exclusions or conditions are given. The intended use case must be inferred entirely from the field list, which is weak routing for an agent surveying 18 siblings.

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

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

Annotations only state readOnlyHint=true and a title; the description adds meaningful behavior: server-side search, tiles returning one entry per day, default limit of 50, and date parsing flexibility. It even discloses the UI3 v91 bug fix context. The crossover alert-side behavior is unusually transparent about a surprising response shape, though it doesn't enumerate all response fields beyond the listed ones. Since annotations are minimal, this description carries the behavioral burden well.

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

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

The description is a single dense paragraph with no wasted words; it front-loads the core purpose and required parameter. The crossover note and UI3 v91 mention are relevant but add length; still, each sentence serves a purpose. It could be improved with slight formatting breaks, but it is efficiently packed.

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 list tool with 8 parameters and no output schema, the description covers the main parameters, their formats, and response-shape caveats. No output schema exists, so the description should explain what is returned; it does list returned clip fields and flags the alert crossover fields, but does not specify pagination or how limit interacts with tiles beyond the default. Given readOnlyHint annotation and the extensive parameter coverage, this is nearly complete.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds meaning beyond the schema by explaining why tiles is useful for calendar views, clarifying that the crossover view values return alert items with an 'msec' field that means alert length, and explaining server-side memo substring search. It also emphasizes that camera is required and 'Index' means all. However, some schema descriptions already cover the same semantics, so the added value is moderate, not exceptional.

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 clear verb-resource pair: 'Recent recorded clips for a camera: path, duration, resolution, flags, memo.' It explicitly contrasts with bi_list_alerts, noting that clips include continuous recordings while alerts are AI/motion events. This distinguishes it well from the sibling that appears most similar.

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 directly says it is 'Complementary to bi_list_alerts' and explains the difference. It also provides a crossover warning explaining that alert-side view values return alert items, a subtle but critical usage detail. Required camera parameter and optional view/date/search/tiles/limit semantics are all covered, including date format alternatives and relative shorthand.

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 adds substantial behavioral context: admin requirement, return envelope shape ({entries, scanned, matched, warning?}), raw mode behavior, and the critical aggregation caveat that count is cumulative and date reflects last summation rather than most recent occurrence. It also warns that level 3 entries are deduped and points to bi_list_alerts for per-event data.

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

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

The description is long but every section earns its place: routing, filter semantics, return shape, and aggregation caveat. It is front-loaded with the most important sibling distinction and remains scannable with clear labels. No filler or repetition of schema content.

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 8 parameters, no output schema, and only a readOnly annotation, the description nevertheless covers return structure, permission requirements, filter behavior, dedup semantics, and how to detect actively firing messages. There are no critical gaps for an agent to call this safely and 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?

Even though schema coverage is 100%, the description adds meaning far beyond the schema: 'limit is applied AFTER filtering', 'regex is xor with match', 'since supports relative shorthand server-side via aftertime', clone cameras log under short names, and the empirical level meanings. This materially improves an agent's ability to call the tool correctly.

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: 'Recent Blue Iris system log entries with optional filters.' It clearly distinguishes itself from bi_list_alerts by explicitly positioning this tool for system events and aggregate counts versus per-alert timestamps. An agent can immediately tell this apart from its siblings.

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

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

The 'Pick the right tool' section explicitly tells the agent when to use bi_list_alerts instead, and what this log is best for: system events and aggregate activity counts. It gives concrete routing guidance without leaving the decision to inference.

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