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

Beyond the read-only annotations, the description discloses many behavioral traits: finding_key stability across rescans, per-run ids, truncation via truncated/truncated_note, and the nuanced empty_scan fields after a scan that found nothing. It also clarifies that findings_kept_from_previous_scan can mean the listed findings are not from the current scan. This is rich, non-contradictory behavioral context.

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

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

The description is front-loaded with the resource definition and then layers in filtering, stable-key guidance, truncation, and empty-scan semantics. It is longer than typical for a one-parameter tool, but most sentences carry operational meaning rather than repetition. The empty_scan paragraph is dense yet earns its place by covering a non-obvious edge case.

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 return-value burden and does so well by describing finding fields, stable keys, truncation indicators, and empty_scan conditions. It also explains how filtering works and when the returned findings may not reflect the latest scan. Combined with annotations covering read-only safety, an agent has enough context 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?

The schema provides an enum but no descriptions, and the description only says the list can optionally be filtered by status. It adds some meaning by calling these lifecycle statuses and noting that statuses may have been assigned by people, but it does not explain the individual enum values or default filter behavior. With low schema coverage, this partially compensates but leaves clear gaps.

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 defines the resource as documented findings for a workspace, specifying they are cross-system discrepancies with evidence, recommendation, and lifecycle status. It distinguishes findings from sibling list tools like list_signals and list_metrics, but it does not use an explicit verb or name alternatives, so it falls just short of the top score.

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

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

It says the list can optionally be filtered by status and advises using finding_key when referring to a finding over time. However, it does not explain when to call list_findings instead of siblings like search or get_map_overview, nor does it state prerequisites or exclusions. This is implied usage rather than explicit guidance.

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