list_companies

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

Annotations already cover the safety profile (readOnly, non-destructive, not open-world), and the description adds non-obvious behavior: every call appends metadata-only receipt lines (tool, company, counts, fingerprints) to a local log, and it writes nothing to Tally. This is exactly the extra context annotations cannot convey.

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?

Front-loaded with 'Start here' and organized around the routing decision, so the important guidance comes first. It is dense and the trailing logging sentence adds length, but each sentence carries load-bearing information rather than filler.

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?

With no parameters and no output schema, the description must carry both selection logic and return-content expectations, and it does so, including the company_guid contract and ambiguity flags. Nothing an agent needs to call it correctly is missing.

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 tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description instead front-loads what the call returns (tuples with company_guid and ambiguity flags), which is useful but belongs to return semantics rather than parameters.

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?

States a precise verb+resource ('Return observed company tuples') and explains the payload's role by naming the exact field other tools need (company_guid). 'Start here' explicitly positions it as the entry point, distinguishing it from the many sibling read tools that require a company.

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?

Gives explicit decision rules: single open company with no named client -> use it; named client matching one open company -> use it; otherwise ask and offer the list. It also states an exclusion ('never guess a company'), leaving nothing to inference.

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