count

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

With no annotations present, the description carries the full burden and does substantial work: it discloses that the return includes the actual executed query plus ⚠️ warnings, and warns that counts after dropped terms or phrase rewrites are not valid for the original query, and that zero hits do not prove a topic lacks literature. The remaining gap is operational detail such as rate limits or failure behavior, but the semantic caveats here are unusually strong.

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 key differentiator is front-loaded in the first clause, followed by parameter rules and then the caveats in descending priority. It is dense but each sentence adds a distinct constraint; the phrasing is compact rather than padded.

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?

Given an output schema exists, the description need not enumerate return fields, yet it still flags the executed-query and warning output. Combined with the snapshot semantics (counts are not the query, zero is not absence) and the pointer to search for full parsing, an agent has enough to invoke this correctly, with only reldate semantics left thin.

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 0% across five parameters, so the description must compensate. It does explain term conventions (English terms, uppercase AND/OR/NOT) and that date parameters follow publication date and mirror search's rules, which covers term, field, mindate and maxdate. However, reldate (a non-obvious relative-date parameter) gets no dedicated explanation, so the compensation is partial.

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 precise verb+resource scope: retrieves only the PubMed hit count, explicitly not the records (题录). That single clause distinguishes it cleanly from the sibling search tool, so an agent can pick correctly without opening either schema.

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 explicit routing: if you need records, use search directly to avoid redundant retrieval, and if you need to confirm a phrase exists, read records or abstracts instead. It also names a concrete alternative call (search with retmax=0, as_json=True) for full parsing, covering both when-to-use and when-not-to-use.

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