record_screening_decisions

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds one genuine behavioral constraint beyond the annotations: include/exclude decisions require a verbatim evidence quote. It does not explain batch/concurrency behavior (e.g. what a stale revision does), so this is solid but not rich.

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?

One front-loaded sentence with zero filler; the evidence constraint is stated immediately. It is arguably too terse for a batch-write tool, but nothing in it is wasted.

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 no explanation. However, this is a batch mutation tool with a revision-based concurrency model (up to 25 decisions, revision from next_screening_batch) and the description does not cover batch semantics, revision conflicts, or what destructiveHint=true means here, leaving real gaps.

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 67%, with run_id, revision and evidence already documented inline, so the schema does most of the work. The description reinforces the evidence requirement for include/exclude, adding slight value, but says nothing about the 1-25 batch size or the uid/reason fields.

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 ('Record screening decisions'), so an agent can tell what the tool does at a glance. It does not, however, distinguish itself from close siblings like set_screening_criteria, next_screening_batch, or review_article, which all live in the same screening workflow.

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 explicit when-to-use guidance or mention of the alternatives it belongs to. The workflow dependencies (that run_id comes from start_search and revision from next_screening_batch) are only in the schema, not the description, so an agent gets no routing help from the text.

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