causal_trace

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

With no annotations provided, the description fully bears the burden. It declares read-only ('does not modify any stored data'), describes the return format ('ordered chain of concepts with confidence scores plus the matching solution' and 'empty chain with a message if no causal path is found'), and includes an explicit example. No contradictions with 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 well-structured: start with purpose, then prerequisites, return behavior, example, and sibling differentiation. Every sentence adds value; no redundancy. The format is front-loaded with the core action.

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 no output schema and no annotations, the description covers all essential aspects: what it does, prerequisites, return on success and failure, an example, and guidance on when to use alternatives. It is complete for the tool's 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 the baseline is 3. The description repeats the schema's explanation for instance_id and problem, adds default for max_depth, and explains tags as 'Optional: narrow search to these tags'. No additional semantics beyond schema are provided.

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 'Root Cause Analysis through memory', tracing a causal chain from root cause to symptom and surfacing a past solution. It distinguishes itself from siblings like recall_best_solution and syndicate_search by emphasizing the full-chain output.

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 states prerequisites ('brain must have lessons stored via learn_from_attempts or brain_from_git') and provides precise differentiation from siblings: 'Use recall_best_solution for direct topic lookup, syndicate_search for community patterns, and causal_trace when you have a symptom and need the full root-cause chain.'

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