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

With no annotations, the description carries the behavioral burden. It states the tool only accepts a known session ID, explicitly denies listing/filtering, and discloses the return format ('one-element sessions array'). It doesn't mention error cases (e.g., invalid ID) or auth/rate limits, but the disclosed restrictions and return shape are substantive. Minor gap: 'same shape as before' is vague without prior context.

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?

Organized with USE WHEN / DON'T USE sections, bullet-like clarity, and front-loaded purpose. Slightly verbose with some redundancy (e.g., 'The only way to use this tool' repeats the restriction stated earlier), but the structure earns high marks overall.

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 an output schema, so return values are covered automatically. The description provides all necessary calling context: required ID, unsupported operations, alternative tools, and parameter nuances. Nothing critical is missing for an agent to invoke it correctly.

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 baseline is 3. The description adds value by clarifying the two ID formats (ses_ vs VS and their meaning), the server_name condition ('required when connected to multiple servers'), and container_id prefix (trc_). These enrich the schema's basic descriptions enough to warrant 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?

The description opens with 'Fetch ONE visitor session by its ID' — a precise verb+resource statement. It also explicitly excludes listing/filtering, clearly distinguishing from siblings like query_sessions and list_events. The inclusion of ID prefix examples (ses_, VS) reinforces the specific scope.

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?

Dedicated USE WHEN and DON'T USE sections give explicit conditions: use when a session ID is referenced, avoid for counts/rates/top-sources, and route to get_report or get_summary instead. It even advises asking the user for a dashboard ID when no ID is known. This is exemplary alternative routing.

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