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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: pagination semantics (offset counts records vs bytes), continuation requirements (follow verbatim until complete=true), truncation behavior (oversized record returns reportState=truncated, no silent shortening), and the meaning of distinct states (pending/failed/etc. never mean validation passed). This is rich, non-obvious behavioral 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 dense but every sentence earns its place. It front-loads the core purpose, then covers section semantics, pagination, continuation, truncation, empty states, and the sibling alternative. It is longer than ideal, but the tool is genuinely complex (10 sections, two pagination modes, continuation protocol), so the length is justified. Minor redundancy: 'no record is silently shortened' restates the truncation behavior already described.

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 the tool's complexity (7 parameters, 10 enum sections, nested filters, output schema present), the description covers everything an agent needs to call it correctly: section selection, pagination units, continuation protocol, truncation handling, empty-section semantics, state interpretation, and the fallback alternative. The output schema exists, so return-value details are already structured. Nothing critical is missing.

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%, so the baseline is 3. The description adds meaning beyond the schema by explaining how offset/limit behave differently per section (records vs bytes), how filters apply to issues only, and how filterId/artifactId function as continuation pins. It doesn't enumerate every parameter, but the schema already does that; the description clarifies the semantics that the schema leaves implicit.

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 a specific verb and resource: 'Read bounded pages from a completed job's immutable report_json artifact.' It then enumerates the distinct sections and their semantics, which clearly differentiates this tool from siblings like artifact_get and job_get. The title 'Read complete job report pages' is reinforced with concrete detail about what each section returns.

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 explicitly states when to use this tool versus alternatives: 'artifact_get remains available to download the complete file.' It also gives section-specific guidance ('Default is issues for validation and summary for scene_apply/export'), explains continuation semantics, and clarifies empty-section conditions. This is comprehensive routing guidance.

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