list logs

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

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly focuses on behavior annotations cannot express: newest-first ordering, successful (non-aborted) exchanges only, secret-scrubbing, the 409 logging_disabled error that prevents misreading an empty list as 'no traffic', and the exact offset-pagination loop. The 409 disclosure alone is high-value operational 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?

Dense but every sentence earns its place: purpose front-loaded, then endpoint+auth scope, then a complete return shape (critical since there is no output schema), then ordering, error mode, pagination pattern, and a cross-tool tip. No fluff, no repetition of annotation content, and the structure follows a natural read→call→interpret flow.

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?

For a 9-parameter, 0-required, no-output-schema read tool, the description covers everything needed to call it correctly: full return payload shape, ordering and filtering semantics, the one critical error case (409 when logging disabled), the pagination contract, and how results feed into evals. Nothing an agent needs to invoke this safely and correctly is left to inference.

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 genuine value beyond the schema by mapping the filter surface in prose, clarifying time-range semantics for start/end, and especially the segment round-trip workflow (row's segment → ?segment= or eval sample_filters.segment), which is operational guidance no schema field conveys.

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?

Opens with a specific verb+resource+scope: 'Browse the workspace's logged chat exchanges (request messages + assistant reply, secret-scrubbed)' with named filters. The 'inspect real traffic before grading, building datasets, or running evals' phrase distinguishes it from siblings like export_logs (bulk export) and get_trace (single trace lookup) without needing their schemas.

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?

Gives clear when-to-use context ('inspect real traffic before grading, building datasets, or running evals') and even shows downstream reuse ('Pass a row's segment back as ?segment= or into an eval's sample_filters.segment'). However, it never names alternatives or states when NOT to use it versus export_logs or screen_my_traffic, stopping short of the explicit routing the top band requires.

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