Get trace content

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

Annotations already declare readOnlyHint=true, and 'Fetch' is consistent with that read-only profile. The description adds useful context about what each include value returns and where trace_id originates, but does not disclose failure modes (e.g., behavior for an unknown trace_id) or response formatting. With annotations carrying the safety burden, 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?

Three sentences with no waste: purpose is front-loaded, parameter semantics are compactly enumerated, and provenance is stated last. Every sentence earns its place; length is proportional to the information density required.

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?

For a simple two-parameter read tool, the description covers what the tool does, the meaning of every parameter value, and how to source the required trace_id. Minor gaps: no hint about the returned content structure (there is no output schema to defer to) and it references get_message_trace, which is not among the listed sibling tools, though the other source get_run_steps is present.

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 0%, so the description carries the full burden, and it delivers: each enum value is mapped to its meaning ('payload' for message body, 'headers' for HTTP headers, 'properties' for exchange properties, 'all' for everything), and the trace_id parameter gets provenance guidance. The schema's raw enum names are cryptic without this elaboration.

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 pair ('Fetch trace content for a specific trace message'), which clearly states what the tool does. The elaboration of the 'include' options makes the scope of 'content' explicit, distinguishing it from sibling trace/logging tools like get_run_steps and get_message_processing_logs.

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 sentence 'TraceId comes from get_run_steps or get_message_trace' provides clear workflow context, telling the agent this tool is a follow-up to those tools and how to obtain the required parameter. It stops short of naming alternatives and giving explicit when-to-use-this-instead conditions, so it is clear context without exclusions.

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