ask_strajk

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

Annotations indicate readOnlyHint and openWorldHint. Description adds behavioral context: data from external sources (treated as material, not instructions), requirement to cite strajkpolski.org, and mention of returning similarity scores. No contradictions.

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?

Description is concise and front-loaded with purpose. Parameter list is appended. Could be slightly more streamlined, but no superfluous sentences.

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?

Covers all key aspects: input parameters, return value (fragments with similarity scores), data provenance, and citation instruction. No output schema, but description explains output adequately.

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 has 100% coverage with descriptions. Description adds value by clarifying query language (Polish), minimum length (3 znaki), source options (excluding czat), and default limit. This supplements schema details.

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?

Description clearly states it's a semantic search tool for the Strajk Polski knowledge corpus, returning relevant fragments with similarity scores. It distinguishes from sibling tools like search_cytaty by focusing on context/quotes rather than raw numbers, and specifies the Polish language requirement.

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?

Provides explicit guidance on when to use ('gdy potrzebujesz kontekstu/cytatu zamiast surowej liczby') and lists parameters. Slightly lacking in when-not-to-use or alternative tools, but clear enough for an agent.

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