swissco_lookup

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

Annotations already declare readOnly/idempotent/openWorld, so safety profile is covered. The description adds genuinely useful behavioral context beyond them: output varies with Zefix PublicREST credentials present in the environment, and optional flags cost extra requests/downloads ('three requests', 'two downloads on a cold cache'). It stops short of describing error/not-found behavior or cache semantics.

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 core statement is front-loaded and efficient, but the long enumeration of every returned field largely duplicates the existing output schema, padding the description without adding decision-relevant information. The credential-conditional grouping is the only part of that list that 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 read-only lookup, the definition covers what an agent needs: the identifying key, the conditional output tiers based on credentials, and the cost of the optional flags. Because an output schema exists, the field list is not strictly required, and the only real omission is failure behavior when a uid is unknown.

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 coverage is 100%, so baseline is 3. The description goes beyond the schema by mapping each optional flag to the concrete fields it unlocks (lei → lei, lei_status, direct_parent, ultimate_parent; finma_licence → finma_licence, finma_category, finma_city, finma_flags), which the schema's terse 'entities that consolidate this one' does not spell out.

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 opening sentence names a specific action and resource: retrieving everything the commercial register publishes about one company (keyed by a required uid). This implicitly separates it from the multi-result sibling swissco_search, but no sibling is named explicitly, so differentiation requires inference.

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?

Usage is implied by the access pattern (single uid in, one row out), and the description explains when the optional finma_licence/lei data is added. However, there is no explicit when-to-use guidance or routing against the eight sibling tools (e.g. when to prefer swissco_search or swissco_finma instead).

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