notebook_status

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

With no annotations, the description must carry the burden of explaining behavior. It discloses that this tool aggregates status and includes source_count, but it does not mention side effects (likely none), permissions, error behavior, or the exact shape of the returned status. It adds useful context beyond the schema but lacks deeper behavioral detail.

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 two short sentences, front-loaded with the main purpose, and the comparison to source_status is valuable. No redundant or filler language.

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?

The tool is simple (1 param, no output schema), and the description gives a high-level idea of the return value (aggregate status + source_count). However, without an output schema or more detail on the response structure, an agent may not know exactly what 'status' entails. The reference to source_status is helpful but assumes familiarity with that sibling.

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 needed to compensate for the notebook_id parameter. It does not explain how to obtain or interpret notebook_id, beyond the schema's bare type and title. For a single simple parameter this is a minor gap, but the rubric requires compensation when coverage is low.

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 uses a specific verb ('Aggregate') and resource ('status across all sources in a notebook'), and clearly distinguishes itself from the sibling source_status by noting 'Same rollup as source_status, plus source_count'. It also captures user intent with 'is my corpus ready'.

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 context for when to use this tool: to get an aggregate view of notebook readiness. It explicitly references source_status as a comparison point, indicating an alternative exists, though it does not explicitly state when to prefer one over the other.

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