athena_orchestrate

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 contributes substantive invariants: 'UNKNOWN never becomes zero', 'gates are fail-closed', and 'scalar NEXT coexists with Pareto alternatives and explicit budget allocation', plus the 'optionally persist' side effect. It does not describe authentication, rate limits, or the exact persistence destination, but the core safety behavior is disclosed.

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 a single dense sentence of roughly 45 words, with the primary action front-loaded and no filler. Every clause contributes meaningful behavioral information, though the semicolon-packed technical phrasing is heavy; overall it is efficient and appropriately sized.

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 a complex nested schema, 9 parameters, no output schema, and no annotations, the description provides rich behavioral invariants but omits parameter semantics and usage guidance. An agent can understand the general operation type but not confidently prepare the inputs for a valid invocation.

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 description coverage is 0%, so the description must compensate for the 9-parameter schema, but it does not explain the required `seed` or most parameters. It references domain concepts like evidence, calibration gates, and budget allocation, but never explicitly maps them to `candidates`, `metric_contract`, `persist`, or other schema properties. Some conceptual meaning is added, but an agent cannot confidently construct a correct invocation from this description alone.

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 'Compile and optionally persist AOR.3 decision state', providing a specific verb ('compile') and resource ('AOR.3 decision state'). The persistence option clearly distinguishes it from sibling retrieval tools like athena_orchestration_get and athena_orchestration_replay. Although AOR.3 is not expanded, the action is unambiguous within the tool family.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention sibling tools such as athena_orchestration_get/replay/recent/robustness, nor does it state any conditions, prerequisites, or exclusions. The only hint is 'optionally persist', but that is a behavioral detail, not a usage guideline.

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