search_works

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context not captured in annotations: simplified output unless raw=True, cursor-based paging with next_cursor, rows capped at 1000, and select for trimming payload. These are concrete expectations that go beyond the safety profile.

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 compact and information-dense. It leads with a clear purpose, then proceeds through usage in logical order. Every line adds value—no filler or redundant phrasing. The multi-line bullet style improves scannability without being verbose.

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?

For a tool with 12 parameters and no schema descriptions or output schema, the description covers the most critical aspects: query modes, filter syntax, pagination, payload trimming, and output format. It lacks explicit details on sort/order/offset and rate limits, but those are minor given the overall thoroughness.

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 0%, so the description carries the full burden for explaining parameters. It covers query, query_bibliographic/query_author/query_title, filter, rows, select, cursor, and raw with meaningful details. It omits sort, order, and offset, but these are relatively self-explanatory for a search API, so the description compensates well overall.

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 "Search Crossref works" which is a specific verb+resource pair, and it explicitly lists content types (articles, books, datasets). This clearly distinguishes it from siblings like search_members or search_journals, making the tool's purpose unambiguous.

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 provides detailed guidance on when to use different query modes (free-text vs field-scoped), filter syntax, rows cap, select, cursor, and raw. It does not explicitly name alternative tools for single-work lookup, but the context is clear enough that an agent would know to use this for searching works rather than get_work.

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