source_wait

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

Even with readOnlyHint=true and destructiveHint=false, the description adds substantial behavior beyond annotations: it discloses the exact aggregate return shape, the meaning of 'ok', the contents of error buckets, partial progress semantics, warning behavior for web pages, and the distinction between input errors (NOT_FOUND before wait) and backend-reported failures. This is rich, non-obvious behavior that annotations alone do not convey.

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 organized into clear paragraphs, front-loads the purpose, uses a code block for the output schema, and every sentence adds critical detail (return shape, partial progress, warnings, error semantics). It is dense but not verbose; all content earns its place given 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?

With no output schema, the description fully specifies the return value (aggregate keys, buckets, counts, ok flag), explains all three input modes, and covers edge cases (unresolved refs, partial progress, advisory warnings). It also references source_read for additional verification. The only minor omission is explicit units for timeout/interval, but this does not undermine overall completeness for an agent.

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 does explain 'sources' (list or comma/JSON string), 'source' (name or ID), and 'notebook' (name or ID). However, 'timeout' and 'interval' are not explained at all—units and semantics are left to inference from their names and defaults. With 5 parameters and 0% schema help, this partial coverage leaves gaps, but the description does meaningfully clarify the core selector parameters.

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+resource: "Wait for sources to finish processing." It clearly identifies the operation and distinguishes it from sibling tools like source_read (which reads content) and source_list (which lists sources). The scope (notebook name or ID) and three waiting modes are all laid out, making the purpose unmistakable.

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 explains when to use the tool (waiting for sources to finish processing) and details the three modes (sources, source, all), which guides selection. It also provides an exclusion: when a READY web-page entry has a warning, the agent should not trust it unconditionally and instead "verify with source_read (detail='full')" — an explicit alternative for that sub-case. This is strong usage guidance.

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