Upload a release asset

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

Goes well past the annotations: discloses the write-mode gate, that uploads are refused outright when FORGEJO_UPLOAD_ROOT is unset, that the file must resolve inside that root, and that 'whatever is read becomes publicly downloadable' — a real security consequence annotations never convey. The non-idempotent behavior (same-named assets coexist) is also explained, which matches the idempotentHint=false annotation rather than contradicting it.

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 sentences, front-loaded with the action and inputs before the environmental precondition and the replacement gotcha. Every sentence carries a distinct, non-redundant piece of information; nothing is padding.

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?

Covers the auth mode, filesystem confinement, failure mode, and the duplicate-asset pitfall — everything needed to invoke safely for a mutation tool with no output schema. The only gap is that the returned asset object/identifier is not mentioned, though with no output schema that is a minor omission.

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 100%, so all five parameters are already documented, including the name default and the FORGEJO_UPLOAD_ROOT constraint on file_path. The description largely restates that (name defaults to the file's own, file must resolve inside the root) without adding format, size-limit, or validation detail beyond the schema, so baseline 3 applies.

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?

Names a specific verb and resource ('Upload a local file as a release asset'), and the 'release asset' framing distinguishes it from the sibling 'create_release' (which creates the release itself) and 'delete_release_asset'. An agent can place it immediately.

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?

States the precondition 'requires write mode', names required inputs, and gives an explicit replacement workflow ('delete the old one first when replacing'). It stops short of naming the sibling delete_release_asset tool directly, so routing relies on inference, but the condition is unambiguous.

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