Upload data

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that uploaded data is immutable and content-addressed, and that the returned hash permanently identifies the bytes. This adds useful context about side effects, though it could have mentioned whether the operation requires authentication or has rate limits, but the description does not contradict anything.

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 concise, uses bullet-like structure in a natural way, and front-loads the core action. Every sentence earns its place: it states purpose, gives usage triggers, routes away from sibling tools, and clarifies parameter handling. No fluff or redundancy.

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 tool with three parameters, an output schema, and no nested objects, the description covers all necessary aspects: what it does, when to use it, how handles parameters, and what it returns. It even addresses edge cases like placeholder values. The existence of an output schema reduces the need to describe return details, but the description still mentions the return hash.

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?

Although the schema descriptions cover 100% of parameters, the description adds critical semantic detail beyond the schema. It emphasizes that the `data` parameter should be taken verbatim from the user's message and includes guidance to avoid substituting or clarifying content. This is significant added value because the schema might not convey that the string is literal content, not a variable reference. The description also reiterates that optional parameters should use defaults and not be asked for.

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 clearly states the tool's purpose: uploading arbitrary text data as an immutable content-addressed blob and returning a Swarm reference hash. It uses a specific verb ('upload') and resource ('text data'), and distinguishes itself from feed operations by explicitly mentioning that it is not a feed operation.

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?

The description provides explicit when-to-use guidance: it tells the agent to use this tool for phrases like 'upload data', 'upload text', 'store data' without mentioning feed, topic, or memory. It also names the alternative tool `update_feed` and specifies when NOT to use this one, making the routing decision unambiguous.

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