agent-trace-auditor

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

No annotations exist, so description carries full burden. It discloses the tool analyzes traces, detects issues, and returns verdict/score/findings. It does not mention side effects or state changes, but as a read-only analysis tool, this is adequate.

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?

Two sentences: first defines purpose, second enumerates detections and outputs. No superfluous text, front-loaded with key information.

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?

The description covers purpose, inputs (trace), and outputs (verdict/score/findings) sufficiently for a tool with no output schema. Could detail the output structure more, but current level is adequate given complexity.

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 100%, so baseline is 3. The description adds value by specifying the default for budget_usd and clarifying that tool_schemas are per-tool field schemas, which is not obvious from the property name alone.

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 the tool performs a 'full audit' of an agent execution trace, listing specific detections (infinite loops, etc.) and return types. This distinguishes it from siblings diff_traces (comparison) and quick_verdict (fast judgment).

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 implies use for comprehensive analysis but does not explicitly state when to use or avoid this tool versus alternatives. No exclusion criteria or when-not-to-use guidance provided.

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

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

No annotations are provided, so the description must bear the burden of behavioral disclosure. It mentions the tool returns score delta, cost delta, etc., but does not state whether the tool mutates data, requires specific permissions, has rate limits, or any side effects. The lack of any behavioral context beyond the output is insufficient.

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 a single, concise sentence that efficiently communicates the purpose and outputs. It front-loads the key action and avoids unnecessary details. Minor improvement could be structuring into two sentences for clarity, but it is not verbose.

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?

The tool is moderately complex (comparing traces) and has no output schema. The description partially explains return values but lacks details on the format or interpretation of score delta, cost delta, etc. Additionally, no usage context or prerequisites are given. The description covers the basics but leaves gaps.

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 67% (2 of 3 parameters have descriptions). The description adds value by explaining the roles of trace_a and trace_b (baseline vs new), but it does not mention the budget_usd parameter, leaving it undocumented in both the schema and description. The description does not compensate for the missing parameter explanation.

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 the tool's purpose: comparing two agent traces to detect regressions. It lists the return values. However, it does not explicitly differentiate from sibling tools like audit_trace or quick_verdict, though the verb 'compare' and 'regressions' imply a distinct use case.

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 provides no guidance on when to use this tool versus alternatives, nor any prerequisites or when-not-to-use scenarios. It only states what it does, leaving the agent to infer usage context.

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

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

No annotations are provided, so the description carries the full burden. It mentions 'fast' and the output includes a 'score and issue counts', but it does not disclose side effects, authorization requirements, or whether the tool is read-only or destructive. This is insufficient for a tool with no annotations.

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 minimal—two short sentences with no redundancy. It front-loads the purpose and use case, wasting no words.

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?

The tool has 2 parameters, no output schema, and no annotations. The description does not explain the return value format, score range, how 'budget_usd' affects the verdict, or any other behavioral details. This is incomplete for a tool used in CI gates where reliability is critical.

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 only 50% (the 'trace' parameter has a description, but 'budget_usd' does not). The tool description adds no additional meaning to either parameter, failing to compensate for the missing schema documentation.

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 the tool provides a 'fast pass/review/block verdict with score and issue counts'. The verb 'pass/review/block' and resource 'verdict' are specific, and the sibling tools are about auditing and diffing, making this tool distinct.

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 explicitly says 'Use in CI gates', giving a clear context for when to use the tool. However, it does not specify when not to use it or compare directly to sibling tools like 'audit_trace' or 'diff_traces'.

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