suggest_detections

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals that results are lean stubs without raw query content, are limited to ~2KB and up to 10 results, and are intended for triage. It does not explicitly state whether the tool is read-only or if there are side effects, but the tone and use case strongly imply a non-mutating lookup.

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 tight sentences with no filler. The core purpose, output constraints, and usage alternative are all front-loaded and every clause adds 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 is complete for a simple read-style tool: it explains what is returned, the format of each stub, the response size limit, and when to use it. With no output schema, it compensates by describing the return shape, so an agent knows what to expect.

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 parameters technique_id and source_type are already fully described in the schema. The description adds context about the output format and mentions 'source' as a stub field, but it does not need to re-explain parameter meanings. Baseline 3 is appropriate because the schema carries the weight.

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 action ('Get detection ideas for a MITRE technique ID') and a concrete output shape ('lean stubs (name, source, severity, log hint)'). It also distinguishes itself from get_detection by explicitly excluding raw query content, making the tool's unique role 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 gives explicit usage guidance: use suggest_detections to find what rules exist before pulling full content with get_detection. This directly tells the agent when to choose this tool over the closest sibling and frames it as a precursor step.

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