swiss_company_search

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

With no annotations provided, the description carries the full burden. It does disclose the authentication requirement (ZEFIX_USER and ZEFIX_PASS env vars) and the need for a free account, which is valuable operational context. However, it doesn't disclose rate limits, whether this is a cost-bearing operation, or error behavior if credentials are missing. Still, the auth disclosure is genuinely useful beyond schema.

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 a single, information-dense sentence that efficiently conveys the source, purpose, and a critical prerequisite. Zero wasted words; every element earns its place.

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 search tool with 4 parameters, no output schema, and no annotations, the description covers the essential prerequisites but misses behavioral details like result ordering, pagination behavior, rate limits, and error handling for missing credentials or no matches. It's adequate for a basic search but lacks depth given the auth complexity and no output schema to fall back on.

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 50% (name and canton have descriptions; active_only and max_results are undocumented in the schema). The description adds the ZEFIX-specific context and auth needs but doesn't explain parameter semantics like what active_only default true means or what max_results caps. With 50% coverage, the description partially compensates but leaves two parameters still under-explained.

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 this searches Swiss companies in the ZEFIX official commercial register, with a specific verb+resource combination. It slightly overlaps with sibling swiss_company_by_uid (which presumably searches by UID), but the description names the ZEFIX source which helps orient the agent. It doesn't explicitly distinguish from swiss_company_by_uid though.

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 mentions ZEFIX as the data source and notes the env var requirement, which implies it's the appropriate tool for commercial register lookups. However, it doesn't explicitly state when to use this vs. swiss_company_by_uid (e.g., name-based search vs. UID-based lookup) or any exclusion criteria. The context of ZEFIX hints at usage but no explicit alternative comparison is made.

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