Limitations that apply to this study

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

Beyond the readOnly/idempotent annotations, the description discloses the tool's core behavior: entries are filtered by study_features, concessions are paired with counters, and already-answered entries are moved into a separate 'retired' set. This gives the agent a clear model of what the tool will and will not return.

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 main action and immediate purpose, then explains the concession-counter rationale, then lists args and returns. Every sentence earns its place and there is no redundant 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?

With no output schema, the description compensates by stating the return shape ('ordered list to write as one Discussion paragraph, plus the retired set'). All three parameters are meaningfully contextualized, including a concrete example for study_features, making the tool fully actionable.

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 meaning beyond the schema: it explains that design can be omitted for limitations common to every design and that study_features 'both trigger and retire entries.' The example feature list clarifies the expected granularity and format.

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 opens with a specific verb and resource: 'Return the limitations a reviewer of this design will raise, filtered to the ones that are actually yours.' It also clarifies what the output is for ('to write as one Discussion paragraph') and distinguishes itself from a generic guidance tool by emphasizing study-specific filtering and concession-counter pairs.

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 clearly explains how to use the tool: provide design and study_features, and it explains the 'retired' concept so the user knows to report those points as strengths in the Methods rather than concessions in the Discussion. It does not explicitly list when-not-to-use or alternatives, but the guidance given is strong and contextual.

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