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

Adds real behavior beyond the annotations: text extraction and indexing side effects, one document per upload_id, a 2-hour expiry on upload_id, and a workspace-settings permission requirement. The one tension is 'Retry-safe with the same idempotency_key' against idempotentHint=false; this is arguably conditional idempotency via the key rather than a flat contradiction, but it is worth flagging as imprecise.

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?

Four tight sentences, front-loaded with the workflow anchor, then optional fields, then the scoping constraints (expiry, client visibility, permissions) and retry semantics. No sentence is filler and each adds an operational fact.

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?

For a 10-parameter mutation with no output schema, the description covers the prerequisite, side effects, TTL, permissions and retry behavior well; return values need not be explained without an output schema. The remaining gap is undocumented non-required parameters such as brand_id and the body/query overrides.

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 only 30% across 10 parameters, so the description should compensate more than it does. It calls out the optional title, description, document_type and tags, but says nothing about brand_id, body, query, or the idempotency_key format, leaving several parameters to the schema alone.

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 and resource ('Finish a Brain document file upload') and immediately anchors it to the sibling step 'aidelly_create_brain_document_upload_url'. It also names the downstream effect (indexed for aidelly_search_brain), so an agent can distinguish it from aidelly_add_brain_document and the URL-creation sibling.

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?

Gives the exact precondition ('after the file was PUT to the upload_url from aidelly_create_brain_document_upload_url') and a usage constraint ('Hidden from browser-sandboxed chat clients'), which is strong context. It stops short of naming an explicit alternative or when-not-to-use case (e.g. small inline documents via aidelly_add_brain_document), so it lands just under full marks.

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