Judge Imported Controls

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

With no annotations, the description carries the full burden and does so: it discloses that it is mutating only when confirm_estimate=True, that it may consume credits, that pricing matches judge_objectives, that it queues judgements, and it enumerates refusal statuses 409/402/503 returned as data rather than exceptions. This is unusually rich behavioral disclosure.

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?

Front-loads the mutating/credit caveat, then uses a numbered two-step list that is easy to follow. Dense but each paragraph (workflow, ungrouped, refusals) earns its place; only minor tightening is possible.

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?

Even though an output schema exists, the description names the relevant return fields (awaiting_judgement, co_ids, scope, ungrouped, estimate, confirmed, queued) and explains refusal shapes, leaving no gap for correct invocation or interpretation.

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 67%; the description explains confirm_estimate's two modes more fully than the schema does, and ties model_id implicitly to the target threat model. It does not add meaning for server_version, but that param is boilerplate.

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?

States a specific verb and resource ('Have the imported controls awaiting their judgement judged') and scopes it to controls saved by import_controls, distinguishing it from judge_objectives / judge_objective. An agent can identify the distinct role this plays in the control workflow.

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?

Gives an explicit two-step protocol (estimate first with confirm_estimate=False, then confirm with True), names prerequisites (controls must be grouped, otherwise use set_mitigation_groups), and states the no-op case ('when nothing awaits, the answer says so and does nothing').

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