zdx_get_deeptrace_health_metrics

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

The annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only'. It adds beyond the annotations by revealing the response shape and processing quality ('curated, nested time-series JSON'), which helps the agent anticipate complex, non-raw output.

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: one core purpose sentence plus a short read-only declaration. It front-loads the key verb, resource, and output format without any filler or redundancy.

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?

Given its simple getter-like read shape, the description conveys the core object and output type, and the schema handles query semantics well. However, with a long sibling list and no output schema, it lacks context around when to choose this tool versus related deep-trace metric/event tools and what specific health metrics will appear.

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 only the optional query parameter in depth, while device_id and trace_id have no descriptions. The main description adds no specific parameter-level semantics beyond implying that the device and trace context comes from a deep trace, so the two required parameters remain under-explained.

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 uses a specific verb and resource: 'Get device health metrics captured during a ZDX deep trace', and adds the useful output structure clue of 'curated, nested time-series JSON'. It identifies the tool's domain but does not explicitly contrast it with sibling deep-trace metric tools like zdx_get_deeptrace_cloudpath_metrics.

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 only implies usage context via 'captured during a ZDX deep trace'. It gives no explicit when-to-use vs. alternatives, prerequisites for obtaining trace_id, or exclusions such as 'for cloudpath metrics use related tools'.

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