Explain Correlation

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

The description explains what the tool returns in detail (channels, dominant channel, artifacts, signal count, quality flags) beyond what output schema could convey. It also discloses the 404 behavior when no edge exists, which is useful behavioral context. The readOnlyHint=true and idempotentHint=true annotations are consistent with the description's read-operation framing, so there is no contradiction. The 404 disclosure adds genuine value not present in 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?

Two dense sentences with zero wasted words. Every clause carries informational weight - the return contents, the intended usage trigger, the order-independence note, and the 404 case. Front-loaded with the primary purpose, followed by usage context. This is exemplary conciseness.

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 an output schema present, so return value documentation is handled there. The description covers the essential behavioral surface: what it computes, what it returns, when to use it, how parameters relate (order-independent), and the error case (404). For a relatively simple two-parameter correlation explanation tool with annotations and output schema supporting it, this description is complete.

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% and both parameters are self-documenting ('First threat ID' / 'Second threat ID'). The description adds one meaningful detail beyond the schema: the pair can be passed in either order (order independence). With complete schema coverage, baseline 3 is appropriate, and the order-independence note justifies not docking further but doesn't elevate beyond 3.

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-resource structure ('explain correlation') with detailed scope: the per-channel similarity decomposition, dominant channel, shared artifacts, signal count, and quality flags. It clearly distinguishes this tool from the sibling get_correlation_path, get_correlation_subgraph, and get_similar_threats by focusing on the evidence/explanation behind a similarity score rather than the path or subgraph.

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 when to use this tool ('Use when get_similar_threats gives a score and you need the evidence behind it'), naming the predecessor tool by name. It also addresses invocation details ('Pass the pair in either order' - order independence) and the 404 error case when no edge exists. This is model usage guidance with explicit trigger conditions and alternative references.

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