search_literature

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

With no annotations, the description carries the full burden and does well: it discloses that the call has a persistent side effect (logging the query with a response hash), explains that hit_count reflects what the engine reported while items are only the first `limit`, and warns that a SEARCHED status with few items reflects the query rather than the field. It stops short of covering failure modes, auth, or engine-specific limits beyond litsense's cap of 100.

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 core action and its logging side effect are front-loaded in the first sentence, and every subsequent sentence adds interpretive value. The parenthetical about litsense and the 100 cap is slightly dense, but nothing is 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, so return-value documentation is not required, yet the description still clarifies hit_count vs items semantics, which is the main interpretive risk. For a three-parameter tool with a full schema this is close to complete, with only error/edge behavior left implicit.

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 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining the relationship between `limit` and the returned items and the distinct meaning of hit_count. The engine-specific syntax nuance is left to the enum descriptions rather than repeated here.

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 ('Run one literature search') and adds the side effect ('record it, with its response hash, in the log'). No sibling tool performs a search, so it is unambiguously distinguishable from check_quote, resolve_identifier, citing_papers, etc.

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?

Usage is implied by the fact that this is the only search tool among the siblings, and the note about missing papers hints at how to interpret results. However, there is no explicit 'when to use this vs alternatives' guidance, no prerequisites, and no statement of when not to call it.

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