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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable context: authentication is required, the signed_in_as account appears in the output, signed-in users may differ between the agent and reader, and the connection is not tied to a single company. These are behavioral nuances not inferable from annotations.

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 long (9 sentences) but each sentence contributes operational value, covering purpose, authentication, usage boundaries, multi-user pitfalls, and follow-up actions. One minor redundancy ('Naming the account turns that from a mystery into one sentence') could be trimmed, but overall it is well-structured and front-loaded with the core purpose.

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 an output schema available (not shown), the description does not need to detail return values. It covers all essential context: what the tool lists, its authentication requirement, exactly when to use it, the multi-user discrepancy risk, and how to proceed with subsequent tool calls. No significant gaps remain.

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 input schema has two parameters (pageSize, pageToken) with 0% description coverage. The tool description does not mention either parameter at all, leaving the agent without any explanation of how to use pagination. Since schema coverage is low, the description was expected to compensate but did not.

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 opens with a specific verb and resource: 'Lists the companies the SIGNED-IN user already belongs to, each with their role, plus that account itself in signed_in_as.' This clearly distinguishes it from sibling tools like company_get_list_companies and explicitly contrasts with formation_start_formation.

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 gives explicit when/when-not guidance: 'Call this only when the user asks about or wants to act on an EXISTING company' and 'Do NOT call it to start a new formation (use formation_start_formation, which is anonymous)'. It also advises on subsequent tool use ('simply pass its company_id to the next tool call') and cautions against guessing company_id.

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