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

No annotations are present, so the description carries the behavioral burden. It clearly states the operation returns a string and is limited to raw text, and the usage guidance prevents misuse. It does not go into edge-case behavior, but for a simple read-like tool this is sufficient.

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?

Every sentence contributes: purpose, when-to-use, when-not-to-use, and the fallback alternative are all packed into a compact description. The critical routing information is 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?

For a one-parameter tool with an output schema and full parameter coverage, the description is complete: it defines what is returned, exactly when to call it, and which sibling to choose instead. Nothing needed for correct selection and invocation 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?

The single parameter has full schema description coverage ('Swarm reference hash'), so the schema already documents it. The description adds context about upload_data-origin references but does not materially enhance the parameter semantics beyond the baseline.

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 names a specific verb ('Download'), a resource ('raw text data from a Swarm reference'), and the result type ('string'), making the tool's purpose explicit. It also implicitly differentiates from download_files by restricting scope to raw text content.

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?

It gives exact conditions for use ('ONLY when the user explicitly asks for text content, string content, or raw data') and explicit exclusions for file/folder requests that route to download_files. It even provides a tie-breaker rule ('When in doubt... prefer download_files'), which is unusually complete guidance.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose mode-dependent behavior ('saves them to disk (in stdio mode) or returns the file list') and that it handles folder manifests. It does not mention overwrite behavior, permissions, or error cases, but the core surprising behavior is covered.

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 sentences, front-loaded with the core purpose, then usage guidance, then the sibling routing rule. Every sentence contributes actionable information with no filler.

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 two parameters, no output schema, and no annotations, the description covers the main usage scenario, mode-dependent behavior, and alternatives. It does not specify what the returned file list looks like or what happens on failure, but enough information is present for an agent to decide to call it and pass the required reference parameter.

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 the baseline is 3. The description adds context by explaining that files from a manifest are written into the destination folder, and it clarifies the stdio-mode dependency, but it largely restates what the schema already documents. It does not materially improve on the parameter descriptions.

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 states a specific verb and resource ('Download a file or folder from a Swarm reference'), and further specifies that it handles both single files and folder manifests. It also distinguishes itself from download_data by naming the alternative and explaining when to prefer it.

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 usage conditions are given: use this tool when the user asks to download and mentions 'file', 'files', 'folder', or does not specify a data type. It also gives a clear exclusion rule: prefer download_data only when raw text/string content is explicitly requested. This is strong routing guidance.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It only says 'Retrieve,' which hints at a read-only operation, but it does not explicitly say whether it has side effects, requires ownership or authentication, or any constraints like rate limits. The description is not misleading, but is far from transparent.

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 one sentence, free of filler, and front-loads the verb and object. Every word contributes to the core message, making it easy to parse quickly.

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?

Given the tool's low complexity, 100% parameter schema coverage, and presence of an output schema, the description is nearly sufficient for an agent to invoke the tool and interpret results. The main gap is the lack of guidance about the optional owner parameter for external/feed memory access, but that is already captured in the schema, so this is a minor shortfall.

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 memoryTopic and owner are already documented with concrete meaning. The description adds 'given a topic,' which aligns with memoryTopic but does not explain the owner field or when it is required. Baseline of 3 is appropriate because the schema does most of the work.

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 states a specific action ('Retrieve') and resource ('the latest data from the feed'), so the tool's core function is clear. It does not differentiate from siblings like download_data or download_files, but the feed-specific wording makes it reasonably distinct.

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 implies when to use the tool—when you want a topic's feed data—but gives no explicit guidance about when not to use it, prerequisites, or alternatives such as update_feed or download_data. With six siblings present, this lack of routing guidance leaves the agent to infer the right choice.

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

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

With no annotations, the description carries full responsibility. It does disclose that the tool writes new data to a mutable feed and that `memoryTopic` must be user-supplied, and it sets expectations about not asking for `postageBatchId`. However, it does not describe side effects like overwriting existing content, behavior if the feed/topic does not exist, or error handling. The word 'update' implies mutation, but the consequences are not fully transparent.

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 well-structured and front-loaded, opening with the core action and then presenting usage rules and optional-parameter policy. Each sentence provides useful guidance, though there is minor repetition around 'the user' and the phrasing could be tightened slightly.

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 three-parameter update tool with a fully covered schema and an output schema, the description supplies the essential routing rules, required topic source, and optional-parameter etiquette. It does not cover edge cases like missing feed creation or failure behavior, but those are not critical for an agent to call the tool correctly in the intended scenarios.

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 the baseline is 3. The schema already provides rich parameter details, including verbatim data handling and server-side hashing of topics. The description adds reinforcement that `memoryTopic` must come from the user and `postageBatchId` is optional, but it does not add semantic meaning beyond what the schema already conveys.

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 states a specific action ('Update a mutable, topic-indexed Swarm feed with new data') that clearly distinguishes this tool from siblings like `read_feed` (read vs. update) and `upload_data` (no topic context). It identifies the verb, the resource, and the operational scope in one sentence.

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 explicitly says when to use the tool ('ONLY when the user explicitly mentions a feed, topic, or memory name'), names the alternative (`upload_data`) for the opposite case, and warns against prompting the user to route here. It also gives clear guidance on the optional `postageBatchId` parameter, telling the agent not to ask unless the user brings it up.

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

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.

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that local paths only work in stdio mode, that the server reads the file itself, that large files upload asynchronously, and that with redundancyLevel > 0 only the tagId is returned immediately. It also states that references are the tool's output, not an input.

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 long but every sentence earns its place: core usage modes, routing to upload_folder, behavioral notes on sync/async uploads, and optional parameters all serve the agent's decision-making. The most critical constraints are front-loaded, and the optional parameters are logically grouped at the end.

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 no annotations and no output schema, the description is remarkably complete. It explains return behavior (reference, tagId, query_upload_progress), deferred uploads, redundancy behavior, and the alternative tool. An agent has enough information to select and invoke this tool correctly in a wide range of contexts.

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 schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains how to pass a filesystem path versus raw text for `data`, notes stdio-only limitation, and details the optional semantics of redundancyLevel and postageBatchId. This goes far beyond the bare schema descriptions.

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 defines the tool as uploading a SINGLE file to Swarm, with specific content modes (filesystem path or raw text). It explicitly differentiates from upload_folder by stating that this tool is for one file only, and clarifies that Swarm references are outputs, not inputs.

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 gives explicit when-to-use and when-not-to-use guidance: if the user mentions "folder", "directory", "the contents of", or requests more than one file, the agent should use upload_folder instead. It also instructs the agent never to ask for file content when a path is given and never to pass a Swarm reference as input.

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

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

With no annotations provided, the description carries the full behavioral burden, and it does so well. It discloses both synchronous behavior (small folders return a `reference`) and asynchronous behavior (large folders return a `tagId` and require polling `query_upload_progress` until processedPercentage is 100). This gives the agent the operational knowledge needed to handle either path correctly.

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 longer than average, but every sentence serves a purpose: trigger phrases, sibling differentiation, sync/async behavior, polling, and parameter usage. Some minor redundancy exists (e.g., 'Optional options' and 'ignore if they are not requested'), but the overall structure is front-loaded with purpose and usage before deferring to parameter details.

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?

Given that there is no output schema and no annotations, the description covers everything an agent needs to call the tool correctly: required path, sync/async return semantics, how to retrieve the eventual reference, and how to treat optional parameters. It also handles nuanced user phrasings that might otherwise route the agent to `upload_file`.

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?

The schema already covers 100% of parameters, so the baseline is 3. The description adds meaningful operational semantics beyond the schema: `folderPath` must be passed verbatim, optional parameters should be ignored unless requested, redundancyLevel defaults to 0, and postageBatchId is only used if provided. This lifts the score above baseline.

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 function: 'Upload a folder (directory)' and goes beyond by explicitly naming the sibling tool `upload_file` as the alternative when the path is a file. It even lists phrasing triggers like 'folder', 'directory', and 'the contents of', making the distinction unmistakable.

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: 'Use this tool whenever the user mentions "folder", "directory", ...' and says to prefer it over `upload_file` when the path type is unclear. It also instructs not to ask for confirmation or re-entering the path, and to ignore optional parameters if not requested.

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