List Co Dispositions

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

With no annotations provided, the description carries the full burden and does well: it declares the operation read-only, lists the fields each entry carries, and explains that expired and revoked entries are intentionally included for auditability. This goes beyond the schema and gives the agent important behavioral context.

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: purpose first, return contents and inclusion behavior second, usage guidance last. Each sentence adds value, including the rationale for including expired and revoked entries, without excessive verbosity.

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?

Given that an output schema exists and the description covers purpose, safety, return contents, and when to use it, the agent has enough context to invoke this tool correctly. Server_version is self-explanatory from the schema, and no pagination details are necessary for a list operation of this scope.

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 description aligns with the schema's kind parameter by mentioning 'risk acceptances, not-applicable dispositions, or both', but the schema already documents kind in detail. It adds little for model_id and nothing for server_version, and with 67% schema coverage the description does not substantially compensate for the undocumented parameter.

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 verb and resource: it lists signed judgments recorded against a model's control objectives, including risk acceptances and not-applicable dispositions. It is clear but does not explicitly differentiate itself from sibling tools like list_risk_acceptances, so the distinction is mostly implicit.

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 tells the agent to read this before authoring a new judgment, warning that an existing or expired judgment may already cover the objective. It provides clear context for when the tool is useful, though it does not explicitly state when not to use it or name alternative tools.

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