cs_search_correspondences

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals several important behaviors: it uses an external correspSearch API, multiple person IDs are combined with AND logic (in the Note), text_query is marked as experimental and undocumented, and pagination details (page is 1-indexed, 100 per page) are specified. It does not explicitly state the operation is read-only, but the search-oriented purpose strongly implies it, and the description otherwise provides substantial behavioral context.

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 well-structured with clear sections (PURPOSE, WHEN TO USE, WHEN NOT TO USE, Args, Returns, Note) and front-loaded with purpose and usage guidance. It is somewhat long due to 15 parameters, but each section earns its place and the length is justified by the tool's complexity. A minor issue is the inclusion of 'ctx' as an argument that is not present in the input schema, but this is likely a framework context and does not significantly detract from clarity.

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 the tool's complexity (15 parameters, no annotations) and the presence of an output schema, the description provides comprehensive context: explicit purpose, when to use/not use, detailed parameter semantics, return type (CorrespSearchResult with pagination info), and an important behavioral note about AND combination. There are no significant gaps, as it covers all critical aspects an agent would need to correctly select and invoke the tool.

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?

The schema has 0% description coverage, so the description must compensate, and it does excellently. Each parameter in the Args section is explained with types, example values, and allowed options (e.g., person_gnd can be a single string or list of IDs, availability options 'online', 'print', 'hybrid', page is 1-indexed with 100 results per page). This adds far more meaning than the bare schema, with concrete examples for nearly every parameter.

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 'Cross-Edition Briefsuche über correspSearch API' and explicitly states PURPOSE: 'Briefe über Edition-Grenzen hinweg finden' (find letters across editions). This clearly identifies a specific verb (search/find) and resource (letters) with a unique scope that distinguishes it from sibling tools like sd_search_letters, which is Schleiermacher-specific.

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 a dedicated WHEN TO USE section listing concrete scenarios (e.g., user wants letters in ALL editions, cross-referencing between editions, comprehensive correspondence network analysis). It also has a WHEN NOT TO USE section explicitly stating that for Schleiermacher-specific search one should use sd_search_letters(), giving a clear alternative and exclusion.

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