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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar for added value is high. The description clears it by disclosing a likely-surprising inclusion behavior ('Every membership stays listed — testers and archived are not hidden'), explaining the lifecycle field's provenance (companies.archived_at), and specifying the row structure (role, lifecycle, about). These are genuine behavioral disclosures beyond the 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?

Four sentences, each carrying distinct value: purpose, inclusion behavior + row structure, lifecycle interpretation, and discovery/disambiguation usage. Purpose is front-loaded and there is zero redundancy or 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?

For a read-only list tool with strong annotations and no output schema, the description compensates well — it explains return structure, lifecycle semantics, and correct usage. However, it never clarifies the effect of the optional companyId input parameter on the result set, and the row-field list ('role, lifecycle, and about') omits name/companyId fields that the later disambiguation guidance implies exist. These are minor but real gaps.

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 the baseline is 3. The description adds downstream context for companyId ('discover valid companyId values before using company-scoped tools'), but it never explains what passing companyId as an input actually does to this listing tool — filtering? scoping? The schema's own parameter text ('Required for company-scoped tools') reads like boilerplate that doesn't fit an optional parameter on a list-everything tool, and the description does not resolve this ambiguity.

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: 'List the companies the current operator can act in (their FreedomOS portfolio).' It further distinguishes scope from siblings like get_company by noting every membership stays listed, including testers and archived — so an agent knows this is the portfolio-level listing, not a single-company fetch.

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?

Explicit when-to-use is given: 'Call this to discover valid companyId values before using company-scoped tools.' It also provides interpretation rules ('Walk lifecycle=active as the district list; do not treat archived as live districts') and a disambiguation protocol ('use about — not the name — to infer WHICH company the user means; if about doesn't settle it, ask rather than guess'). Nothing is left to inference.

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