trace_in_stack

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

No annotations are provided, so the description carries the behavioral disclosure burden. It reveals the tool is lightweight, limited to abstraction card or path-prefix matching, and excludes contract artifacts and PR links—useful behavioral context. However, it does not state read-only nature, outcome when no match is found, or operational details of the matching modes.

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 with zero waste. The first sentence fronts the core behavior and scope; the second states the exclusions and points to the alternative. Excellent structure for quick agent parsing.

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 single-parameter tool with an output schema and a clear sibling list, the description covers the essential boundaries: what is matched, what is excluded, and where to go for richer traces. It lacks a positive 'use this when' statement, but the negative scoping and sibling pointer make the tool usable without further inference.

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 input schema already fully describes the parameter with 100% coverage, including path-prefix matching for file paths and abstraction card matching for concept names. The description restates the same concepts without adding new meaning, so the baseline 3 applies.

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 states a specific scope: lightweight stack location via abstraction card or path-prefix pipeline matching. It clearly differentiates from sibling trace_contract by explicitly noting what it does not include (contract artifacts, PR links). The verb is somewhat implicit, but the resource and limitations are clear.

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 names trace_contract as the alternative for enriched cross-layer traces and notes exclusions ('No contract artifacts or PR links'), which informs when not to use this tool. It does not give a positive condition like 'use when you only need lightweight location', but the contrast is sufficient.

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