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

Annotations only declare readOnlyHint=false, idempotentHint=false, openWorldHint=false and destructiveHint=false; the description goes well beyond them by disclosing resource consumption plus a browser approval step, that secret_name is a reference and never a value, that 'until' defines the stop conditions, and that a lost response leaves an unknown outcome. The non-idempotency warning is consistent with idempotentHint=false.

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?

Front-loaded with the three kinds, then requirements, then return value, then risks — a logical order with no filler sentences. It is telegraphic and jargon-heavy ('admitted connector_document_digest', 'sealed capture'), which costs a little readability but not correctness.

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 still states what comes back (resource id and observed state), names the follow-up tool, covers the credential-safety and unknown-outcome hazards, and flags resource consumption and approval. Remaining gaps are minor per-kind timing parameters that the schema already constrains.

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, but the description adds real meaning: the members-vs-series_id mutex ('never both'), the security semantics of secret_name, and the role of 'until' as stop conditions. It does not explain seconds, volume_policy, or no_data_timeout_seconds, which remain schema-only.

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?

States a specific verb (starts) and resource (stream) and then disambiguates the three kinds it can create — probe (bounded observation, no sealed capture), capture (bounded retained evidence), subscription (durable recording). It also implicitly separates itself from get_stream and control_stream_subscription by naming get_stream as the follow-up rather than the operation itself.

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?

Explicitly states which inputs apply to which kind ('Supply admitted connector_document_digest, registry_id and exact members; a subscription can instead name series_id, never both') and routes the agent forward ('Next: get_stream with that kind and id'). It also gives the operational rule for a failure mode ('A lost response is an unknown outcome: never repeat blindly').

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