notion_get_file_upload

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is clear from structured data. The description adds a meaningful behavioral constraint: routing through the governed connector authority. It also notes that `effect` is required and must be read, which is useful context beyond the schema. However, it does not describe what response the agent should expect or how large/expensive the operation is.

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 compact and structured with a clear Args list. It front-loads the tool identity and the routing constraint. The Args block is useful for discoverability even though it doesn't explain semantics. No filler or repetition of the input schema titles, though it does repeat the schema's `effect` const without adding much.

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?

The tool has an output schema and annotations that cover safety, so the missing return-value explanation is less critical. However, with zero parameter documentation in the schema and no semantics in the description, and no guidance on which Notion resource a file upload refers to or how `arguments` should be structured, the description is not complete enough for an agent to invoke this correctly without external knowledge. The sibling group `notion_complete_file_upload`, `notion_create_file_upload`, `notion_list_file_uploads`, `notion_send_file_upload` makes the need for differentiation even more pressing.

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 carries the burden of explaining parameters, and it does not. It lists parameter names in an Args block, but provides no semantics for `arguments`, `project_id`, `project_ref`, `connector_account_ref`, or `idempotency_key`. The only parameter that gets any behavioral explanation is `effect` ('must be read'), which the schema already constrains with `const: "read"`. With 7 parameters and zero schema descriptions, this is a significant gap.

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 identifies the operation as `get_file_upload` for the Notion connector, which is specific enough to name a resource and verb. However, it doesn't state what the operation actually does (e.g., 'retrieves a file upload record') or how it differs from closely related siblings like `notion_complete_file_upload`, `notion_create_file_upload`, or `notion_send_file_upload`. It reads as a wrapper-level description rather than a user-facing purpose statement.

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?

There is a mention that it 'routes only through the exact project/account governed connector authority,' which hints at when the operation can be used, but there is no guidance on when to choose this tool over sibling file-upload operations, nor any exclusions or alternative recommendations. The agent is left to infer usage from the name and the sibling list.

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