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

With no annotations, the description fully carries the transparency burden. It discloses that events are reprojected from status_history, the origin field, PII restrictions on clinical fields for non-admin keys, pagination behavior, and the critical caveat about sc.resolved events not being emitted. This is exemplary disclosure.

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 a dense block of text but every sentence adds vital information: return shape, filters, PII, backfill caveat, alternative tool, and auth requirement. It could be improved with bullet points or section breaks, but it remains reasonably sized for the tool's complexity.

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?

This is a complex read tool with no output schema and no annotations. The description covers return structure, event types, pagination, filtering, PII handling, a subtle behavioral caveat, and the recommended sibling tool for current state. It is nearly complete for an agent to select and invoke 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 description coverage is 0%, so the description must compensate. It explains event_types with an example, from_sequence as a cursor, and limit with default/max. However, orgSlug, session_id, and apiKey are not explicitly described, though their names are self-explanatory. Overall, it adds meaning beyond the schema, but not complete coverage.

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 clearly states the tool gets the SCEvent stream for a session, a specific resource and action. It explicitly differentiates from lifecycle_get_state by noting the latter is for current resolution status, and the events stream is historical reconstructions.

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 gives direct guidance: use this for historical SCEvent streams and for current status use lifecycle_get_state.sc_resolution instead. It also clarifies when sc.resolved events are not emitted (backfill policy), preventing incorrect usage.

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