next_parent

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It details the return structure and emphasizes the order of operations (read before mutating). It implies a read-only nature through 'Get' and 'before editing', and even mentions 'the standard error dict'. However, it does not explicitly state side-effect-free behavior or discuss auth/rate limits, so it's not a full 5.

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 with a clear purpose statement. It includes usage instructions, a detailed return format, and a cautionary note, all of which are useful. It is somewhat dense but each sentence contributes value; the return format might be redundant given the output schema, but it remains helpful for quick reference.

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 relatively simple getter tool, the description provides the essential context: when to call it, what it returns, and a common mistake to avoid. Since an output schema exists, the description need not detail all return fields. The main gap is the lack of parameter semantics, but overall the tool is adequately described for an agent to use it correctly.

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 input schema has 0% description coverage for its two parameters (run_id, island), and the tool description does not mention them at all. It adds no meaning about what these parameters represent, their formats, or how they affect the returned data. The names are somewhat self-explanatory from context, but the description fails to compensate for the schema's lack of detail.

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 clearly states the tool's purpose: 'Get the parent and evidence needed for one mutation cycle.' This specifies a concrete verb and resource, and the instruction 'Call this at the start of every worker cycle' distinguishes it from sibling tools like 'discoveries' or 'best' by framing it as the preparatory step for mutation.

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 explicitly states when to use the tool ('at the start of every worker cycle') and what to do with the returned data ('Read the parent files, every inspiration, every discovery, the operator hint, and any crossover parent before editing'). It also warns against mutating before reading inspirations and discoveries, providing clear usage guidance.

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