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

Despite annotations covering safety (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false), the description adds substantial behavioral context the annotations cannot: it warns 'never credential values', explains that 'a named secret is enrolled in workspace settings', discloses that no network connection is started, and advises reusing idempotency_key. This is genuinely useful 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?

The description is dense but front-loaded with the action and the target, then follows with warnings, outputs, and next steps. Every sentence carries operational value; there is no filler.

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 no output schema, the description helpfully names the return values (stream_connector_document_id, document_digest) and their meaning. It also covers the series case. One minor gap: it does not describe behavior on duplicate or conflicting document_name registration beyond the idempotency hint.

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 carry the parameter burden, and it does. It explains document_name format ('.json name'), what document should contain ('the canonical document object, never credential values'), and gives a precise instruction for idempotency_key ('Reuse ... when reconciling registration'). It also clarifies the derived document_digest value and how to use it.

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 names a specific verb (registers) and two specific resources (inline connector or rotating-series document) and ties them to the required document_name parameter. It clearly distinguishes itself from siblings like create_stream_registry and start_stream by stating 'Starts no network connection or recorder.'

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?

It explicitly names the next step ('Next: create_stream_registry with admitted digests') and the reconciliation condition ('Reuse idempotency_key when reconciling registration'). It also gives a clear exclusion ('Starts no network connection or recorder'), so an agent knows this is an admission step, not an activation step.

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