regenerate_controls

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It opens with 'Mutating', explains soft-delete semantics (changed/disappeared controls are soft-deleted and queryable via get_controls(include_deleted=True)), states that unchanged controls keep their metadata, and notes that the tool waits for background job completion. This is thorough and actionable.

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 and front-loaded with a clear purpose statement, followed by behavioral details, scoping rules, and alternative usage. Every sentence adds distinct value; there is no filler or redundant repetition.

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 complex mutating tool with background execution, soft-delete side effects, preservation rules, optional scoping, and an output schema, the description covers all key operational aspects and even references a sibling alternative. It is complete enough for an agent to confidently select and invoke the tool.

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 schema already covers 80% of parameters with descriptions. The description adds meaningful co_ids semantics by clarifying that only those COs' controls are regenerated and all others are left as-is, and that omitting co_ids rebuilds everything. It doesn't explain server_version, but the high schema coverage reduces the burden.

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 verb and resource: 'Regenerate controls from the model's control objectives' and 'Re-authors controls from the current COs.' It also distinguishes itself from the sibling tool remap_control, which is explicitly called out for mechanical mapping fixes.

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: omit co_ids to rebuild everything, provide co_ids to scope regeneration, and prefer remap_control when only stale/orphaned mappings need fixing. It also explains background job behavior and completion waiting, making when-to-use vs alternatives clear.

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