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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a useful data note (visitor_id is a string representing a 64-bit number) and the endpoint path, but says nothing about paging behavior or result ordering beyond what the schema implies.

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?

Three tight sentences with the resource and returned fields front-loaded, followed by the disambiguation and endpoint. The field list is dense but every item maps to a real returned column, so it earns its space.

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, and the description compensates by enumerating the returned session fields, which is exactly what an agent needs to know about the response shape. Combined with the sibling routing note, it is nearly complete; only explicit pagination guidance is missing, though the schema's offset description covers 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?

Schema description coverage is 100% across all 33 parameters, including filter-syntax conventions, enums, and the next_offset paging hint, so the schema carries the parameter burden. The description adds no parameter-level detail (no mention of date range, filters, or limit) and only notes the visitor_id type, which concerns returned data rather than inputs. Baseline 3 is appropriate.

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 the specific resource (individual visitor sessions) and enumerates the per-session fields it returns, plus the backing endpoint. It does not open with a crisp verb+scope sentence, but the resource and the sibling it is not (pirsch_get_session) are both explicit, so an agent can tell it apart from the aggregate statistics siblings.

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 names the alternative explicitly: 'Use pirsch_get_session for one session's page views and events.' That is clear routing guidance. It does not, however, say when to prefer this list over aggregate tools like pirsch_get_totals or pirsch_list_pages, so guidance is clear but incomplete.

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