Payaion

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. Beyond that, the description supplies genuine context: no API key is needed over stdio, and the return payload includes title, price, file info and a /m/<hash> market page URL — details an agent cannot get from the annotations.

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-loaded with the core purpose, then filtering, then the return shape, then the auth note — a sensible ordering. There is minor redundancy between 'Search and browse' and 'Filter by keyword, category, and paginate', but no wasted sentence.

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?

Four optional parameters are fully covered by the schema and an output schema exists, so the description need not explain return values in depth. What it lacks is the relational context — how results lead into purchase_asset or get_download_url, and what 'active' excludes — but nothing prevents a correct call.

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%, with q, page, pageSize and the category enum all documented inline, so the baseline is 3. The description only restates that filtering happens by keyword, category and pagination, adding no defaults, limits or syntax beyond the schema.

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 pair and resource — 'Search and browse active listings on the Payaion marketplace' — with the scope qualifier 'active'. It does not explicitly distinguish itself from the closest sibling, list_on_marketplace, so an agent must infer that one browses others' listings and the other publishes its own.

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?

Mentions what can be filtered and that results paginate, which implies the discovery use case, and adds 'No API key required over stdio' as an environment note. However, it never states when to choose this over list_on_marketplace, nor that browsing is the natural precursor to purchase_asset or get_download_url.

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?

Annotations already declare it is a non-read-only, non-destructive, open-world write. The description adds genuinely new behavioral context beyond them: an 8-level nesting cap and the sibling-uniqueness constraint on names, both operationally important. It stops short of describing what happens on a duplicate-name or depth violation, leaving error behavior implicit.

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 short sentences, front-loaded with the core action and followed by the two constraints an agent actually needs before calling. Nothing is redundant with the title or 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?

With an output schema present, return values need no explanation, and the description covers the mutation's key guardrails (depth, uniqueness, naming). Only error/failure outcomes for violating those guardrails are left unstated, a minor residual gap for a two-parameter tool.

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 both parameters are already documented, which sets the baseline at 3. The description adds some value by stating the 8-level depth limit and the sibling-uniqueness rule, but it does not extend name syntax or parentId semantics beyond the schema's own text.

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?

Opens with a specific verb and resource ('Create a storage folder'), which is unambiguous against siblings like delete_folder or update_folder even without being named explicitly. It does not explicitly contrast with siblings such as move_file or upload_file, which keeps it just short of a 5.

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 parentId guidance ('pass parentId to nest... or omit it for a top-level folder') tells the agent how to use a parameter but not when to prefer this tool over alternatives or what prerequisites exist. Usage is implied by the create-vs-manage sibling set rather than stated.

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?

Adds real value beyond the annotations: it explains that files survive and are moved back to the storage root, which is precisely the context needed to reconcile a 'delete' verb with destructiveHint=false. It does not state whether removing subfolders is reversible or what permissions are required.

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 short sentences, each earning its place: the action first, then the non-obvious side effect, then the boundary against file deletion. No filler and the key surprise (files are preserved) 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, the description covers the essential semantics: what gets removed and what does not. The only meaningful omission is recoverability of the deleted folder structure and any permission requirement.

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 folderId parameter is fully documented in the schema (100% coverage, including which tools produce the id), so the description need not restate it. The description adds nothing about the identifier and the 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?

States a specific verb and resource ('Delete a folder') plus scope ('and its subfolders'), so the agent knows exactly what is affected. It separates the action from file deletion, but no sibling tool is named (and no delete-file tool appears in the sibling list), so routing is inferred rather than explicit.

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 usage by contrasting folder deletion with deleting files ('a separate, explicit action'), which hints at when this tool is the wrong choice. It gives no positive guidance on when to prefer delete_folder over update_folder or move_file, and no prerequisites are stated.

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?

Adds substantial context beyond the annotations: the file is not deleted, the share link stops selling, buyers who already paid retain download access for their 30-day window, and ownership by the agent key owner is required. This is consistent with destructiveHint=false and clarifies the blast radius of the operation precisely.

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-loaded with the mutation itself, then immediately the side effects and permission requirement. Every sentence carries distinct information, though the density makes it slightly heavier than needed.

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?

With an output schema present, return values need no explanation, and the description covers side effects, buyer impact, and authorization. The only gap is not pointing at list_on_marketplace for the reverse operation, which lives in the dashboard rather than as a sibling action.

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 coverage is 100% and the uploadId parameter already includes an example format, so the schema carries the parameter documentation. The description adds only the ownership precondition tied to the key owner, not additional uploadId semantics.

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 ('Take your listing off the public Payaion marketplace') and implicitly contrasts with the list_on_marketplace sibling. An agent knows exactly what state change this produces without reading the schema.

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?

Clear context for when to use it (removing a live marketplace listing) and what to do afterwards (re-price in the dashboard to sell by link only). It never explicitly names list_on_marketplace as the inverse operation or states when-not to use it, so it stops short of full alternative routing.

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?

Annotations already declare a safe read-only, non-destructive, closed-world operation, yet the description adds real value: the URL is shareable without authentication, an API key is required, and a keyless caller cannot mint a link for an upload it cannot prove ownership of. The only gap is that it never says how long a 'fresh' URL stays valid.

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 short sentences, each doing distinct work: what it returns, the prerequisite, the sharing/auth model, and the alternative. The key facts are front-loaded 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?

With an output schema present, return-value explanation is unnecessary, and the description covers purpose, precondition, auth, and the alternative path. The only missing operational detail is URL lifetime/expiry, which matters given the word 'fresh'.

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% and the single uploadId parameter is documented with an example format, so the schema carries the load. The description adds nothing about the parameter itself, which matches the baseline for a fully documented one-parameter schema.

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?

A specific verb and resource ('Get a fresh shareable download URL for a previously uploaded file') that clearly separates this tool from upload_file, upload_from_url, and get_upload_status. It even clarifies the distinction between this fresh URL and the downloadUrl already returned by an upload.

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 states the precondition ('The file must be in READY status') and an explicit when-not path: keep the downloadUrl returned by upload instead, because it belongs to the file rather than the caller. That is both a condition and an alternative, so little is left to inference.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about return values and the downstream signing/purchase flow, though it does not discuss permissions or failure cases.

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 concise sentences with no wasted text. The purpose and pre-purchase requirement are front-loaded, followed by the key return behavior and downstream use.

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 is simple and the description covers the essential workflow: check requirements, learn free versus paid, and pass the x402 object to purchase_asset. Annotations cover safety and an output schema exists, so no further return-format explanation is required.

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%, and the single uploadId parameter is already documented in the schema. The description confirms that the tool operates on a marketplace asset but adds no further syntax or format detail beyond that 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?

States a specific verb and resource: retrieve payment requirements for a marketplace asset. It clearly distinguishes this pre-purchase check from purchase_asset by describing the returned free/paid status and x402 payment requirements object.

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?

Explicitly says to call this before purchasing and that the returned x402 object must be passed to purchase_asset. This gives clear workflow context, though it does not state exclusions or alternatives beyond that primary path.

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?

Annotations already declare readOnly/non-destructive, so the description wisely focuses elsewhere: it lists the exact status states, notes whether the file is ready for download, and discloses the guest-vs-API-key limits. The auth note is real context, though it is somewhat generic to the whole server rather than this call.

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 first three sentences are well front-loaded and earn their place, but the trailing sentence about stdio API keys, guest uploads, 100 MB, and selling is off-topic for a status-check tool and dilutes focus.

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?

With an output schema present, return values need no explanation, and usage guidance plus status enumeration cover the call correctly. The only noise is the tangential credential/marketplace remark, which adds confusion rather than completeness.

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 coverage is 100% and the single uploadId parameter is fully documented in the schema, so the description adds nothing about parameter syntax. 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?

States a specific verb (check) and resource (processing status of a previously uploaded file), and immediately enumerates the status values returned. It is clearly distinguishable from siblings like list_storage, get_download_url, and transfer.

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?

Explicitly says it is rarely needed because 'transfer' handles polling automatically, and narrows use to timed-out uploads or manual inspection. Both the when-to-use and the better alternative are named.

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?

Annotations declare readOnly=false, openWorld=true, destructive=false, but the description adds the genuinely useful context the annotations lack: state prerequisites, ownership requirement, and the external/public effect of publishing to a buyer-facing marketplace. It stops short of explaining failure modes (e.g. what happens if status isn't READY) or whether listing is reversible.

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 short sentences, front-loaded with the action and resource, followed by prerequisites and the return value. Every sentence carries information; nothing is redundant.

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 action, prerequisites, ownership requirement, and the resulting listing URL, and an output schema exists so return details need not be expanded. It leaves out what an agent should do if preconditions are not met, which is the remaining gap.

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 constraints on title, description, tags, and category are already fully documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline 3 case.

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 ('List an already-uploaded file on the public Payaion marketplace'), names the platform, and clearly distinguishes itself from siblings like delist_from_marketplace and browse_marketplace. An agent can identify the operation without opening the schema.

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?

Provides concrete preconditions for use: upload must be in READY status and have a price set, and the caller must own the upload. It does not explicitly name the alternative (delist) or say when not to use this tool, which keeps it short of a 5.

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?

Annotations already declare readOnly/non-destructive/closed-world, so the safety profile is covered. The description still earns credit by disclosing return semantics that matter operationally — folder paths, file counts, plan usage, and that returned ids are the handles other folder tools consume. It stops short of noting pagination or result-size limits for large accounts.

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 short sentences, front-loaded with what is returned, then the optional-scope rule, then the sequencing hint. No restatement of the name or title, 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 one-optional-param read tool with full annotation coverage and an output schema, the description covers everything an agent needs: scope behavior, returned inventory, and its role as the entry point for id-dependent folder operations.

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 coverage is 100% and documents the 'root' alias, so baseline is 3. The description adds behavioral meaning: omitting folderId targets the root's files while the folder listing is returned regardless, clarifying that this is an optional scope selector rather than a required filter.

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?

Specific verb plus resource ('List the account's storage') with an explicit inventory of what comes back: every folder with full path and file count, plus files in one folder. This clearly separates it from the mutation siblings (move_file, delete_folder, update_folder) without needing to name them.

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 an explicit parameter-based branch ('Omit folderId to list files sitting at the root') and an explicit sequencing rule ('Start here before moving, renaming or deleting anything — the ids it returns are what the other folder tools take'). That is when-to-use plus dependency on siblings, stated outright.

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?

Annotations already declare non-read-only, non-destructive, open-world behavior; the description adds genuinely useful context beyond that — the null→root fallback and the guarantee that share link, price and expiry are untouched. It stops short of covering failure modes (nonexistent folder, invalid uploadId) or permission requirements.

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?

Two sentences, front-loaded with the core action and the root special case, then the key invariant. No filler 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?

An output schema exists so return values need no explanation, and annotations carry the safety profile; the description supplies the one non-obvious semantic (null → root) and the metadata invariant. Only error/permission behavior is left uncovered, which is minor for a 2-param tool.

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 coverage is 100% and already documents both params, including 'null/root' for folderId, so the description largely restates schema semantics. Baseline 3 applies since the schema does the heavy lifting.

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 ('Move an uploaded file into a folder') plus the root-target case, so the operation is unambiguous. It implicitly separates itself from the sibling `transfer` by noting this only re-files the item, but it never names a sibling explicitly.

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 clear conditions for use: move into a folder, or pass folderId: null to move to root. It does not state when-not to use it or point to alternatives like `transfer` or `update_folder`, so exclusions are absent.

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?

Annotations already declare the destructive and open-world nature, but the description adds crucial context: this is a monetary purchase that consumes a signed x402 payload and returns a receipt plus download URL. It does not spell out irreversibility or error behavior (e.g., what happens if the payload is invalid or the asset is already owned), which keeps it from 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?

Three tight sentences, front-loaded with purpose, then prerequisites, then post-purchase behavior. Every sentence carries actionable information with no restatement of the name or title.

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?

Despite the mutation, nested payload, and payment prerequisite, the description covers the full call sequence, payload origin, and immediate follow-up action. With an output schema present and annotations covering safety, it is complete enough for an agent to invoke correctly.

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 coverage is 100%, so the baseline is 3. The description adds value by explaining where paymentPayload comes from (a signed x402 payload from the buyer's wallet, derived via get_payment_requirements) and what uploadId refers to, which is more than the schema alone conveys about the payload's origin.

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 (finalize purchase of a paid marketplace asset) and explicitly distinguishes itself from the prerequisite sibling get_payment_requirements. An agent immediately knows this is the payment-settlement step, not the requirements-fetch or download step.

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 an explicit ordered workflow: call get_payment_requirements first, sign with the EVM wallet, then invoke this tool with the signed payload. It also tells the agent what to do afterward (GET the directDownloadUrl with X-Aion-Key), leaving no ambiguity about when this tool is the right one.

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?

Goes well beyond the annotations: the annotations only say it is not read-only and is open-world, while the description discloses that no API key is needed over stdio, the guest tier caps (100 MB, 24-hour link), that a key raises limits and unlocks selling, that idempotencyKey is ignored without a key, and — critically — that payments are final and a mistyped payout address is unrecoverable.

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-loaded with the core capability in the first two sentences, and the auth/limits footer is genuinely load-bearing rather than filler. It loses a point for the run-on final paragraph where a missing space ("content' (base64 fallback).Over stdio") breaks the flow of an otherwise dense block.

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 input-source selection, auth tiers, guest limits, and payment irreversibility for a 12-parameter, zero-required-parameter tool, and an output schema exists so return values need not be described. Minor gaps remain: nothing about link expiry once a key is set, or about what happens to pricing when no key is present besides payoutAddress.

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 coverage is 100%, so the baseline is 3, and the description earns extra credit by stating the mutual-exclusion rule that the schema itself does not encode: exactly one of filePath, url, or content. It also flags filePath as stdio-only and zero-token, which shapes which parameter an agent should prefer.

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 ("one-shot file transfer") plus the composite scope: upload, price, and marketplace listing "all in a single call." The "single call" framing implicitly distinguishes it from the atomic siblings upload_file, upload_from_url, and list_on_marketplace, and the mention of a returned download URL completes the picture.

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 an explicit selection rule for the three input sources ("Provide EXACTLY ONE of: filePath, url, or content") and states clearly when an API key is or is not needed, including guest limits. It does not, however, explicitly route agents to upload_file or list_on_marketplace when only part of the workflow is needed.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds a genuine behavioral rule beyond annotations: a folder cannot be moved into itself or its own subfolders, which tells the agent about a validation failure mode it must avoid.

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 short sentences, zero filler, with the capability stated first and the operational and constraint details following in priority order. Nothing could be removed without losing information.

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?

An output schema exists and the input schema is fully documented, so the description only needs to cover intent and constraints, which it does. The main remaining gap is that it says nothing about permissions or what happens to a folder's contents when it is moved.

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 coverage is 100%, so every parameter is already documented in the schema, including parentId accepting null or 'root' and name being optional. The description largely restates the null-to-top-level behavior rather than adding new semantics, so the 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?

The opening sentence names the specific resource (folder) and the two operations it supports (rename, reparent), which lets an agent tell it apart from create_folder/delete_folder. It never explicitly contrasts itself with move_file, though the folder-vs-file distinction is implied only by the noun.

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 states the key operational condition (pass parentId: null to return to top level, omit to leave unchanged) and one hard constraint (no moving into self/subfolders). However, it gives no guidance on when to prefer this tool over a sibling such as move_file, and no prerequisites or permission context are mentioned.

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?

Annotations only declare it is a non-destructive write to an open world; the description adds the real behavioral facts: it returns immediately with PENDING_UPLOAD, requires manual polling, size limits vary by plan (Basic 500 MB / Pro 1 GB), guest mode without a key is capped at 100 MB with a 24-hour link, and a payout address for paid downloads is irrevocable. Those are irrecoverable-consequence warnings not present in the annotations.

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-loaded with the purpose and the sibling redirect, then lifecycle, limits, and parameter rules follow in a logical order. Slightly dense with a missing space at 'lifecycle.Over stdio', but nearly every sentence carries non-redundant information.

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 7-parameter upload tool with an output schema already covering return values, the description supplies the remaining gaps an agent needs: async lifecycle, polling requirement, transport-dependent path support, plan-based limits, guest-mode constraints, and parameter interactions. Nothing required to invoke it correctly 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 coverage is 100%, so the baseline is 3, but the description adds the crucial mutual-exclusivity rule ('Provide EITHER filePath (stdio only) OR content (base64)') and ties parameters to auth state (payoutAddress only without a key, idempotencyKey needs a key). It stops short of covering every parameter, but the either/or constraint is the highest-value piece of added meaning.

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+resource ('Low-level upload') and immediately distinguishes itself from the sibling 'transfer' tool by explaining the exact difference (transfer handles polling for you). An agent can pick between upload_file, transfer, and upload_from_url without opening any schema.

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?

Explicitly names the preferred alternative ('Prefer the transfer tool instead') and the condition for choosing this one ('Use only when you need explicit control over the upload lifecycle'). It also states the follow-up obligation (poll get_upload_status yourself), which is exactly the kind of guidance that prevents wrong tool selection.

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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing the async PENDING_UPLOAD return, the plan-based size ceilings (Basic 500 MB / Pro 1 GB), that private/internal URLs are blocked, and the guest-mode limits without an API key (100 MB, 24-hour link). These are real constraints an agent cannot infer from structured fields.

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-loaded correctly — routing advice and the async warning come first, caveats last. However, the final clause ('a key raises the limits and lets you sell') is compressed into a run-on sentence with a missing space after 'lifecycle.', which slightly hurts readability.

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?

Despite an output schema existing, the description still explains the salient return state (PENDING_UPLOAD) and the polling obligation, plus auth-mode-dependent limits. Nothing an agent needs to invoke this correctly or interpret the immediate result 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter context the schema does not: the no-key guest mode is what makes payoutAddress meaningful and idempotencyKey irrelevant. That clarifies the operating mode that governs two optional params, though it does not add anything beyond the schema for url/fileName/pricePerDownload.

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 the specific verb+resource ('Low-level upload from URL') and immediately distinguishes itself from siblings by naming 'transfer' as the preferred tool and 'get_upload_status' as the required follow-up. An agent knows exactly what this does and does not do without opening the schema.

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 routing guidance: prefer 'transfer' because it polls automatically, and use this one 'only when you need explicit control over the upload lifecycle.' It also states the required follow-up action (poll get_upload_status yourself), so both when-to-use and what-happens-next are covered.

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