Ask Jev for typed decisions (Decision API at https://api.typesafe.ai)

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

Annotations already mark this read-only, open-world and non-destructive, and the description substantially exceeds them: it states the payload is sent to an external API, that API charges may apply, that question IDs are never sent to the model, and that the call returns raw judgments, probabilities, confidence and token usage.

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?

Dense but front-loaded, with the mode semantics appearing before the caveats. Slightly marred by repeating the API URL already present in the title and once more mid-paragraph, which is wasted space in an otherwise information-rich description.

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 nested-input tool with an output schema, the description covers the important things an agent must know: remote destination, charge implications, mode semantics, batching constraints, and that no actions are executed. Credential/authentication setup is only implied by the 'configured models' wording, which is the one remaining gap.

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 100%, so the baseline is 3, but the description adds real semantics the schema cannot express: choice selects from supplied labels, score maps onto 2–10 ordered levels starting at 0, and noul returns probability of yes rather than intensity. It also clarifies that IDs are not model instructions and that model only overrides the model name, not the credential or destination.

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 ('Evaluate supplied context using the configured decision models') and enumerates the three judgment modes (choice, score, noul) with their exact semantics. An agent can tell precisely what the call produces without opening the schema.

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 concrete operational guidance: batch independent narrow questions in one call, include an other/none choice when appropriate, use caller-defined policies for uncertainty, and questions cannot use each other's answers. It also disclaims behavior ('does not execute selected actions'). There is no sibling tool to route against, so a when-not-to-use clause is the only missing piece.

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