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

With no annotations provided, the description carries the full burden. It discloses that container_hash is a secret half of the dual-key auth-token cache lookup, may be null on legacy deploys, and describes the fallback to register_and_provision. It also notes that `domain` may be null on freshly-created containers. These are behavioral nuances an agent needs to handle correctly.

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 longer than typical, but it's well-organized with a clear opening statement, a bulleted 'USE WHEN' section, and a returns clause. Each part carries essential information for an entry-point tool, though it could be slightly tightened by moving some contract details to a linked doc. Still, it earns a 4 for efficient structure.

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?

Given this is a complex, entry-point tool with an output schema, the description covers all necessary aspects: purpose, usage triggers, return fields, special-case handling (null domain, legacy hash), and the OAuth contract. It leaves no critical gap for an agent to safely invoke it.

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 schema already describes `server_name` ('Filter to a specific server. Omit to list containers from all servers.') at 100% coverage, so the baseline is 3. The description adds value by mentioning 'you need the server_name for multi-server setups,' which clarifies when to actually use the parameter, pushing it to a 4.

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 specific verb ('Lists') and resource ('every tracking container the user can access across all connected servers'), and immediately frames it as the entry-point tool. It distinguishes itself from siblings by naming the tools that require a container_id (get_report, get_summary, list_events, list_sessions) and by explaining the OAuth fallback path, making its role unambiguous.

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?

Has an explicit 'USE WHEN' section listing concrete scenarios: starting any session, when the user names a brand without a trc_ ID, for multi-server setups, and the OAuth fallback contract. It also tells the agent to match against the `domain` field and skip null domains, giving precise routing guidance vs. other tools.

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