gazette_search_publications

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds significant context: which rubrics are included/excluded, behavior when no rubric is provided, language deduplication and hit count nuance, and the effect of the only_language parameter. 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 a use-case statement, search scope, exclusions, parameter list, and a note on hit count. It is front-loaded. While slightly lengthy, every section provides necessary context for an AI agent.

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 (multiple parameters, special behavior on rubrics and language), the description is comprehensive. It covers search scope, excluded rubrics, parameter details, return format, and edge cases like language deduplication and hit count. The return value is adequately described even without an explicit output schema shown.

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 input schema already includes detailed descriptions for each parameter, so baseline is 3. The tool description adds extra value by explaining the effect of combining rubric with canton, the injection of all rubrics when rubric is omitted, and the hit count and language deduplication behavior, which go beyond the schema.

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 it searches official publications in gazette rubrics by keyword, rubric, canton, and date. It positions itself as the general entry point for 'what was officially published about X?' and distinguishes from siblings by mentioning specific use cases and what it does not cover (e.g., personal data rubrics).

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 the tool ('general entry point'), and clearly states what it does not handle (rubrics with personal data, person name search). It implies alternatives for excluded cases, though it does not name sibling tools directly.

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