get_controls

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It reveals a critical side effect (first call may trigger control generation), explains inline vs. background completion, and clarifies the meaning of orphaned/tombstoned controls. This is exemplary transparency beyond what any annotation could provide.

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 structured into clear paragraphs and sentences, each earning its place. It front-loads the core purpose, then adds side-effect warnings, filtering guidance, and dual output modes. Despite length, it feels efficient and avoids redundancy with the schema.

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 tool with 11 parameters, a side-effectful generation trigger, and output schema, the description is remarkably complete. It covers what the tool does, when to poll, how to handle orphaned controls, and how to switch between detail and summary modes. Nothing critical is left unexplained.

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 91%, so the baseline is 3. The description adds meaningful context beyond schema for key parameters: include_orphaned (default exclusion rationale), control_id (detail mode), and summary_only (lightweight output). It also explains the orphaned field on returned controls. This exceeds baseline but doesn't cover every parameter, though the schema descriptions handle those.

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 opens with a clear verb+resource statement: 'Get implementation controls for a threat model.' It further specifies the exact purpose (controls to satisfy control objectives) and distinguishes itself from related tools by explicitly referencing get_control_generation_status for polling and noting the control_id detail mode vs. summary_only listing.

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 context: when results look incomplete, poll get_control_generation_status and re-read once complete. It also clarifies default behavior around orphaned controls and how to override with include_orphaned=True. However, it stops short of explicitly naming alternative tools for other scenarios (like get_control for single-control detail), relying on parameter guidance instead.

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