slack_upload_file

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the description's job is to add context: it does, disclosing that the file is uploaded as the user, that a self-DM requires im:write, that filesystem access is sandboxed to SLACK_FILE_ROOTS, and that the message style gate applies. It omits size limits and failure behavior, so not a 5.

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-loads the action, then lists per-parameter guidance in a compact line-per-parameter layout with little waste. The cross-reference to slack_send_message's style gate assumes prior knowledge of a sibling, which costs a bit of clarity.

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 mutating, multi-parameter upload tool with an output schema and annotations, the description covers identity, scoping, threading, and path sandboxing. Gaps remain around the undocumented workspace/allow_promise parameters and any size or failure constraints, but nothing critical to calling it is missing.

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 compensate and it largely does: channel_id formats, thread_ts semantics, file_path constraints, title default to filename, and initial_comment via the style gate. Two of seven parameters, workspace and allow_promise, are never explained.

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 (upload a local file to a Slack channel/DM) plus the identity it acts under (AS THE USER) and an optional comment. It is trivially distinguishable from slack_download_file and from the message-editing siblings.

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 concrete usage conditions: channel_id accepts C/G/D or a U id for a DM (with im:write caveat) and thread_ts turns the upload into a thread reply. It also states exclusions (hidden files and ~/Library are refused, path must be inside SLACK_FILE_ROOTS). It stops short of naming an alternative tool or when-not to upload.

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