list_companies

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real context beyond that: the data is fetched live from Számlázz.hu, and there is a default-company fallback used by other tools when the company parameter is omitted. That fallback semantic is the kind of behavior annotations cannot express.

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?

Two compact sentences with no filler, and the core scoping information leads. The second sentence mixes the switching instruction into the same breath, which is efficient but slightly dense; nothing is wasted though.

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 zero-parameter read tool with no output schema, the description does most of the work by explaining what the result represents: the accessible companies plus the one used by default. It stops short of describing the shape of each entry (name vs. id fields), which is the only meaningful gap given no output schema exists.

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 the schema carries nothing to explain, and the baseline is 4. The description still adds value by pointing at the company parameter that exists on the sibling tools and explaining how a value from here feeds into it.

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 names the resource (the companies the configured Számlázz.hu login can work in) and its scope (read from Számlázz.hu), plus the key fact that it reveals the default company used when none is given. It does not use an explicit verb like 'list', and it never names a sibling tool, but the resource is specific enough to separate it from the invoice-oriented siblings.

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?

It gives actionable guidance for switching companies ('pass the company name or id in the other tools' company parameter'), which is genuinely useful. However it never states when an agent should call this tool — e.g., to discover company ids before create_invoice — so the trigger for invoking it is only implied.

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