analyze

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the operation is read-only, that historical_agreement is the default and only report, that it scans persisted consensus panels, and that an empty corpus returns an empty report with explanatory notes. This is thorough and honest about edge-case behavior.

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 front-loaded with the core action and read-only nature, then efficiently covers the only report, the scan behavior, the interpretive caveat, and the empty-corpus edge case. Every sentence contributes substance with no filler.

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 to cover return values, so the description only needs to cover invocation semantics, which it does completely: the parameter default, valid value, corpus being analyzed, read-only nature, and empty-corpus behavior. An agent has everything needed to invoke and interpret the tool 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 schema provides a single report parameter with zero description coverage, so the description must compensate. It fully does so by stating that report="historical_agreement" is the default and only valid report, leaving no ambiguity about what value to pass.

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 states a specific verb and resource: 'Analyze the kept run corpus' and immediately narrows to the only report, historical_agreement, which scans consensus panels and reports co-voting agreement between distinct lineages. This clearly differentiates it from broad analysis or other read-only tools like review or activity.

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?

It gives clear context on when to use the tool: to get an observational signal for roster choice, and it explicitly warns against misusing it as a vote discount or correctness measure. It does not explicitly compare with sibling tools such as consensus, but the intended use is well framed.

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