gazette_search_detailed

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

Annotations already declare readOnlyHint=true, etc., but the description adds substantial behavioral context: parallel execution of detail fetches ('Hier laufen die Detailabrufe parallel'), the green gate filtering ('Post-Fetch-Green-Gate'), identical semantics with gazette_search_publications, and that top_n defaults to 3. No contradiction with annotations.

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 sections (<use_case>, explanation, when-to-use alternatives, args). It is front-loaded with the primary use case. However, it is somewhat lengthy (multiple paragraphs) and could be more concise without losing important details. Each sentence contributes, but some repetition exists.

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 (aggregated search+full text, parallel calls, relationship with multiple siblings, procurement shortcut), the description is remarkably complete. It covers the behavioral model, green gate filtering, identical filters to sibling, when to use alternatives, and the top_n parameter. The output schema exists, so return values are handled.

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%, so the description must compensate. It explicitly defines top_n (including range and default) and mentions that other fields are identical to gazette_search_publications. While the schema provides detailed descriptions for all parameters, the description could be more explicit about key parameters like rubric, canton, etc. It adds some value but not full compensation.

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 clearly states the tool's purpose: to answer a question needing both hit list and full text in one step. It uses specific verbs ('Sucht... UND liefert') and distinguishes from siblings by explaining it's an aggregated tool that saves multiple calls. The differentiation from gazette_search_publications, gazette_get_publication, and gazette_search_procurement is explicit.

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 explicit guidance on when to use this tool and when to use alternatives. It lists specific scenarios ('Nur die Trefferliste gewünscht → gazette_search_publications', 'Volltext zu einer bekannten ID → gazette_get_publication', 'Mehr als 5 Volltexte → einzeln holen') and also mentions the procurement shortcut with rubric='OB-<Kanton>'.

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