survey_observable_events

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

The annotations specify destructiveHint=true and readOnlyHint=false, implying the tool may have destructive or non-read-only side effects. The description, however, portrays a purely analytical, deterministic survey that 'returns' counts and events, with no mention of any mutation or destructive action. This directly contradicts the annotations, making the description misleading regarding safe invocation.

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 well-structured: it opens with a clear question, explains core behavior, then offers usage guidance and population caveats. Each sentence provides meaningful context (e.g., sensor differences, relation to sibling tools, determinism, cost). While slightly dense, it avoids fluff and earns its length.

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

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

Although the description covers purpose, usage, and return contents thoroughly, it omits any mention of destructive side effects or non-read-only behavior that the annotations indicate. Given that an output schema exists and parameters are fully documented, the description should have addressed the tool's actual side-effect profile. This critical omission makes the description incomplete and potentially unsafe.

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 covers all 7 parameters with descriptions (100% coverage), so the baseline is 3. The description adds a couple of contextual notes (e.g., sensor resolution details, 30-day window cap), but these are already present in the schema's parameter descriptions. No significant extra meaning is provided beyond the schema, so a 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 opens with a specific question and clearly defines the tool's function: to evaluate which events in a window a given in-app sensor can resolve, return counts, breakdown by required resolution, and top events with rationale. It explicitly distinguishes itself from siblings like rank_imaging_priority and query_signals by contrasting population and units, making its purpose unique and concrete.

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 guidance: 'Prefer this over asking about events one at a time' and explains it is exhaustive, cheap, and the honest way to assess observability before committing collection effort. It also differentiates from rank_imaging_priority and query_signals, and instructs to read collection_ready per event for taskability, providing clear when/when-not usage.

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