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

With no annotations provided, the description carries full behavioral responsibility. It explicitly reveals that every membership stays listed, testers and archived memberships are not hidden, and each row exposes role, lifecycle, and about. This gives the agent a clear, no-surprises mental model of the response and its interpretation.

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 dense but structured: primary purpose first, then membership semantics, row content, and finally concrete usage guidance. Every sentence contributes either operational meaning or disambiguation strategy, and nothing feels redundant.

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?

There is no output schema, yet the description communicates the row shape and the active-versus-archived interpretation well. It is nearly complete for a list tool, but it does not explicitly clarify whether/p how the optional companyId parameter filters the returned list or what happens with large result sets.

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 description coverage is 100%, so the baseline is 3 even though the tool description adds no detailed parameter semantics. The description's reference to discovering `companyId values` gives some context, but it does not explain how the optional `companyId` parameter affects this particular list call, leaving a minor 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 leads with a specific verb and resource: 'List the companies the current operator can act in (their FreedomOS portfolio).' It clearly differentiates this from singular company tools by adding portfolio semantics, row contents, and the active-versus-archived lifecycle distinction. Even without checking siblings, an agent knows exactly what this tool returns.

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 contains explicit, actionable guidance: 'Call this to discover valid companyId values before using company-scoped tools,' and it tells the agent to walk lifecycle=active as the live district list, not to treat archived as active, and to prefer `about` over the name. It even specifies the fallback behavior: ask rather than guess.

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