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

Goes well beyond the annotations, which only say it is a non-read-only, non-destructive, open-world, non-idempotent operation. The description adds the return contract (signed upload_url plus a content-type header to PUT, an upload_id valid for 2 hours), the permission requirement, and retry semantics via idempotency_key — useful nuance given 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?

Three dense sentences ordered by importance: what it does and returns, the follow-up call, then eligibility and permissions. No filler, and the operational constraints are front-loaded.

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?

No output schema exists, yet the description fully specifies the return shape and lifetime, the downstream call, the client-eligibility constraint, and the permission prerequisite — everything an agent needs to invoke this correctly or route to aidelly_add_brain_document.

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 coverage is only 50%, and the description compensates by naming the allowed file types (PDF, DOCX, TXT, Markdown), the 10 MB cap, and the meaning/behavior of idempotency_key. It does not mention brand_id or explain the body/query override parameters, so a small gap remains.

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?

Precise verb+resource: 'Start a Brain document file upload', with accepted formats and size cap stated. It also distinguishes itself from aidelly_add_brain_document and points forward to aidelly_complete_brain_document_upload, so an agent can place it in the right step of the flow without opening any schema.

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?

Explicit when-to-use and when-not-to-use: 'Works only for clients with direct network access to Supabase storage, such as Claude Code or a local CLI; the hosted server hides it from browser-sandboxed chat clients, which use aidelly_add_brain_document instead.' It also states the required permission and the mandatory follow-up call.

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