Yumi Cost-Aware Diagnostic Planner

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclaiming inference of truth/timing/costs, which tells the agent this is a pure deterministic computation over provided data rather than an estimator or side-effecting operation.

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?

A single dense sentence that is front-loaded with the primary action and then the input provenance and boundary condition. Nothing is redundant, though the semicolon-joined clause makes it slightly heavy to parse.

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 nontrivial planning tool with no output schema, the description names inputs and the general output (a policy plus expected costs) but does not describe the shape or semantics of the returned plan. Complex nested inputs (probes, outcomes maps) also get only a name-drop, leaving gaps an agent must infer from the schema.

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 carry the load, and it does enumerate the input concepts (hypotheses, relative weights, probes, costs, complete deterministic outcomes) that map onto the nested schema fields. It adds the crucial notion of "complete" outcomes and "relative" weights, though it doesn't detail constraints like the 12-item caps.

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 ("Plans") and a specific resource ("a finite adaptive diagnostic policy and expected costs"), and names the exact provenance of its inputs ("caller-supplied hypotheses, relative weights, probes, costs, and complete deterministic outcomes"). An agent can tell precisely what this tool computes 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?

The scope is implicitly clear from the purpose, and the closing clause ("it does not infer real-world truth, timing, or costs") usefully bounds when the tool is and isn't applicable. However, there is no explicit statement of when to reach for this tool or what precondition (e.g. a fully-specified hypothesis/probe space) must hold, so usage is implied rather than stated.

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