yaaif_ops_telemetry

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does declare 'READ-ONLY', which is a critical behavioral trait, and notes the tool proxies telemetry-service. It does not describe output format, pagination behavior, or side effects beyond the read-only nature. The schema hints at caps (max_items default 40) and summary options, but the description itself adds little beyond the read-only label. This is adequate but not rich.

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 extremely concise: two short sentences with no filler. It front-loads the read-only attribute, states the resource list, and gives a usage hint. Every word earns its place. Perfectly sized for the information conveyed.

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?

This is a complex tool with 11 parameters, six resource types, and no output schema. The description provides only a high-level summary and a usage hint, but does not explain how to assemble the correct parameter set for each resource, what the tool returns, or how to interpret results. The schema fills some gaps (required identifiers, caps), but the description does not synthesize the operational workflow. For an agent to use this tool correctly across all resource types, it would need to parse the schema descriptions carefully; the description alone is insufficient. Given the complexity, a 2 is appropriate.

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 64%, meaning some parameters (limit, offset, include_raw, summary_only) lack descriptions in the schema. The tool description lists the resource enum values, but those already appear in the schema. It does not explain the conditional relationships between resource and identifier parameters (e.g., that session_id is required for messages, events, insights; request_id for flow_events; ambient_run_id for ambient_logs; desktop_run_id for desktop_logs) — though the schema does describe these per parameter. The description adds minimal value over the schema and fails to compensate for the undocumented parameters, so a score of 2 is warranted.

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 it is a READ-ONLY telemetry drill-down tool with a resource parameter that enumerates six telemetry types. It mentions the underlying service path and proxy, and gives a usage preference ('Prefer after yaaif_ops_analyze'). However, it does not explicitly contrast with the many sibling tools that target specific resources (e.g., yaaif_ops_session_messages, yaaif_ops_flow_events), so an agent might not immediately know when to use this unified tool versus the dedicated ones. Still, the core purpose is 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 a clear sequential hint: 'Prefer after yaaif_ops_analyze', which tells the agent when in a workflow this tool fits. It does not, however, state when NOT to use it, nor does it name alternatives like the dedicated session/worker log tools, nor explain the conditional identifier requirements (e.g., which param is needed per resource). The guidance is minimal but present, earning a mid-range score.

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