zdx_list_device_deep_traces

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

The description confirms read-only behavior, which duplicates readOnlyHint=true, but it adds value beyond annotations by disclosing the return shape: "one row per trace (id, status, session name, app, ISO timestamps)" and the fact that results are full records. This is behavioral/return-format context that annotations don't cover.

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: purpose first, then read-only clarification, then return-format and follow-up guidance. Zero fluff, every sentence earns its place, and the most actionable information (what the rows contain and how to use trace_id) is front-loaded.

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 discloses the essential return fields, reducing ambiguity. Params are minimal and the query param is thoroughly documented in-schema. The only gap is no mention of pagination/limits for large result sets, but for a read-only list tool with safety annotations, coverage is strong.

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 50%: the query parameter has a rich description (JMESPath syntax, snake_case warning, example), while device_id is self-evident from its title. The tool description adds mild value by noting "full records" (the default when query is omitted), but the heavy-lifting param guidance lives in the schema. A baseline-3 score 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 verb+resource: "List deep-trace sessions for a ZDX device (full records)." It clearly distinguishes from siblings — it's the list operation versus zdx_get_device_deep_trace (single fetch) and the other zdx_get_deeptrace_* metric/event tools, and from zdx_list_devices (lists devices, not traces).

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 follow-on usage: "Use a returned trace_id with the deep-trace metric/event tools or zdx_get_device_deep_trace." This establishes the workflow context well. However, it does not explicitly state when NOT to use this tool or name alternative filtering approaches (e.g., zdx_list_devices for device lookup), so it lacks explicit exclusions.

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