bi_get_alert_image

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.