get_saturation

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

No annotations are provided, so the description carries the full behavioral burden. 'Evaluate' implies a read-only computation over a run, but the description never confirms this, nor does it disclose cost, whether it triggers computation, or what happens if the run is still in progress. It adds only the vague concept of 'marginal yield' without explaining it.

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 tight sentence with no filler, and the core purpose is front-loaded. It is dense rather than padded, though the undefined jargon slightly reduces immediate readability.

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?

An output schema exists, so return values need not be explained, and there is only one parameter. However, with no annotations and no explanation of the stopping criteria or marginal-yield methodology, an agent cannot tell what trigger conditions make this call appropriate.

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 schema does not document run_id. The description implies operation on 'a run', which maps reasonably onto the single required run_id parameter, but it adds no format, provenance, or lookup detail beyond that implication.

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 ('Evaluate') and a specific subject (marginal yield and saturation stopping criteria for a run), which an agent can distinguish from siblings like get_coverage or get_research_state. The phrasing is dense and jargon-heavy, but the resource and function are identifiable.

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?

There is no guidance on when to call this versus get_coverage, get_research_state, or step_research, all of which live in the same research-lifecycle neighborhood. No prerequisites, no exclusions, no timing cues about when saturation checking matters.

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