AIToURL

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the three return states and that 'done' carries the file's public link, which tells the agent what to expect from the call. It omits whether 'pending' requires re-polling or how long before 'expired' occurs.

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?

One front-loaded sentence that names the action, ties it to the creating tool, and lists outcomes with zero filler. Every clause carries 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?

There is no output schema, and the description compensates well by describing the return states and the public link on completion. For a one-parameter read-only status check, that is nearly complete; only polling/timing expectations are unstated.

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?

With a single parameter at 100% schema description coverage, the schema already defines upload_id and its origin. The description only reinforces the link to create_upload_link and adds no format or constraint detail beyond it, so the baseline of 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 description states a specific verb and resource ("Returns the status of an upload link") and ties it directly to the sibling that creates those links (create_upload_link). It also enumerates the possible outcomes, so an agent can distinguish it from upload_file, get_file, and create_upload_link 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?

The phrase "created with create_upload_link" makes the usage condition clear: this is the follow-up check after creating an upload link. It stops short of explicit exclusions or polling guidance (e.g., how long to wait while pending), but the when-to-use context is 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?

Annotations already declare write, non-destructive, idempotent behavior, but the description adds two non-obvious traits: missing parent folders are created as a side effect, and public links are unaffected by moving files. The plan restriction is also useful operational context. It omits what happens on duplicate paths, which would have pushed it higher.

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 plan restriction and the core action. The public-link sentence is slightly tangential but still conveys folder semantics; nothing is padded.

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 full schema coverage and annotations covering safety and idempotency, the description is nearly sufficient. The main residual gap is what the tool returns (e.g., created folder identifier) since there is no output schema, but 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 coverage is 100% and the single path parameter is already documented with the same example in the schema. The description's only added meaning is that the path is hierarchical and parents are auto-created, which is mild value over a fully-documented 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?

The description states a specific verb and resource ('Creates a folder') and immediately clarifies the input form ('from a path like Clients/Dupont'), which disambiguates it from sibling tools like create_upload_link or upload_file. It does not explicitly contrast itself with any sibling, so it falls 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?

'Pro plan only' gives a real prerequisite that an agent must check before calling. However, there is no guidance on when to use this versus related tools such as upload_file (which may also create folders) or move_file, and no statement about what happens if the folder already exists despite the idempotent annotation.

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 cover the safety profile (non-read-only, non-idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: link expiry (1 hour, one-time use), plan-based size ceilings, the fact that a Pro file_id replacement preserves the existing link, and that folder paths are auto-created. Return values are only implied (upload_url, page_url appear inside instructions) rather than stated, which keeps it off 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?

Every sentence carries operational content — fallback paths, size thresholds, curl syntax, plan gating — and the core fact (one-time, 1-hour link) lands early. It is dense and reads like a runbook rather than being front-loaded with the primary outcome, but there is little dead weight.

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 no output schema, the description must carry the response shape, and it does so implicitly by referencing upload_url and page_url as things the agent will hand out or use. Combined with the fallback flows and plan limits, an agent can act correctly; an explicit statement of the returned fields would make it complete.

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 all three parameters are already documented, including the Pro-only nature of folder and file_id and the link-preserving replace semantics. The description largely restates the file_id behavior rather than adding new syntax or edge-case meaning, 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 description names the concrete artifact it produces ('Creates a one-time upload link valid 1 hour') and scopes it to files that already exist with explicit size limits. The opening framing ('Preferred way to publish a file that already exists') is slightly off-key for a tool that only mints a link, but the verb+resource are unambiguous once past the first clause.

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 an explicit decision tree: try a direct HTTP PUT to upload_url first, fall back to upload_file for files under ~100 KB, and for larger files hand the user page_url or the network-settings advice. It also carves out the Pro-only replace path via file_id. This is exactly the when-to-use vs. sibling-alternative guidance an agent needs.

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 destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds one genuinely new behavioral fact, that the public link stops working immediately, but stops short of covering the remaining relevant behaviors: whether deletion is recoverable, what happens to shared links issued to others, or what error surfaces when the file_id does not exist. Credit is therefore limited to partial additional context.

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 short sentences, front-loaded with the destructive verb and followed by the most consequential side effect. No filler, though the second sentence could have been merged or extended at no cost.

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 single-parameter destructive tool with full annotation coverage and no output schema, the description is largely sufficient: the agent knows it is permanent and that links break. Missing only edge-case behavior such as not-found handling or permission requirements.

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 file_id is fully documented in the schema, including provenance ('returned by upload_file or list_files'). The description adds nothing about parameter 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 description states a specific verb and resource ('Permanently deletes a file'), which is immediately distinguishable from the closest sibling, delete_folder, by its object. It does not, however, explicitly name that sibling or contrast the two, so the differentiation comes from the name rather than the prose.

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?

There is no guidance on when to call this rather than alternatives such as delete_folder, replace_file, or simply moving a file. No prerequisites, no mention of confirming destruction, and no stated exclusions.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description's real contribution is scoping the destruction — only the empty folder is removed, never its contents — but it says nothing about what happens on a non-empty folder (error? partial delete?) or about permission requirements, leaving a meaningful behavioral gap.

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, none wasted, with the action front-loaded before the precondition. Slightly clipped at the end, but every clause carries 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 one-parameter mutating tool with no output schema, the description covers the essential facts: what it removes, the emptiness precondition, and what it will never remove. The main omission is failure behavior on a non-empty folder, which the agent would benefit from knowing.

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% with a single well-documented path parameter, so the baseline of 3 applies. The description adds no format, resolution, or path-rooting detail beyond what the schema's example 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?

"Deletes a folder" is a specific verb plus resource, and "Files are never deleted by this tool" draws a clear line against the sibling delete_file. It stops short of explicitly naming the sibling it replaces or contrasting with rename_folder, so it is clear but not fully differentiated.

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 precondition is stated directly: the folder "must be empty: move or delete its files and subfolders first," which tells the agent when this tool will succeed and what workflow precedes it. It never names the specific sibling tools (move_file, delete_file) to use for that prep step, so the routing is implied rather than explicit.

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?

The annotations establish that this is a read-only operation, and the description adds that it retrieves both details and stats for one file. It provides no further behavioral context, such as what statistics are included or how an invalid or inaccessible file is handled.

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 single sentence is direct, front-loaded, and free of unnecessary wording. It communicates the core result and single-file scope efficiently.

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 simple one-parameter read, the description, schema, and annotations provide enough information to select and invoke the tool. Because there is no output schema, the vague phrase "details and stats" leaves the returned content unclear, and explicit sibling routing would further improve selection.

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 file_id is already well documented, including its length constraints and sources. The description adds no parameter meaning beyond that schema, so the high-coverage baseline 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 description clearly states the operation and resource: returning details and statistics for a single file. The single-file scope gives some separation from list_files, but it does not explicitly distinguish the tool from siblings such as list_files or search_files.

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?

Usage is implied: use it when details and stats for one known file are needed. The schema helpfully explains that file_id can come from upload_file or list_files, but the description gives no explicit when-to-use guidance, exclusions, or alternative tools.

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 behavior beyond the annotations: size limits per plan (25 MB Free / 250 MB Pro), the accepted file-type list, that the real type is detected from content, and that Pro users can pass file_id to swap the file while keeping the same link. This tells the agent about authorization tier requirements and surprising side effects that the openWorldHint/idempotentHint flags do not convey.

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 core action and return value, then layers constraints in a logical order (URL rules, limits, allowed types, Pro replacement). The file-type enumeration is long but earns its place by preventing failed calls.

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 no output schema, the description still tells the agent what comes back (a permanent public link) and covers the practical failure modes (non-direct URLs, size caps, unsupported types). For a single-required-parameter import tool, nothing essential 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 real meaning: the URL must point at the file itself rather than a page, and the file_id replacement path is tied to the Pro plan and link preservation. It does not elaborate on tags/folder semantics, which the schema already handles well.

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: downloads a file from a public http(s) URL on the server and returns a permanent public link. This clearly separates it from upload_file (local content) and replace_file, since nothing passes through the caller.

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 when-to-use framing ('best for files that are already online... nothing has to pass through you') plus explicit constraints on which URLs work (direct file links, not web pages; use direct download links for Drive/Dropbox). It does not name the sibling alternative to use for local files, so the routing is implied rather than explicit.

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 openWorldHint=false, so safety is covered. The description adds useful value by naming the returned fields (public links, download counts, folder), but says nothing about ordering, pagination, or result limits for an account with many files.

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 tight sentences with zero waste; the core action and returned data are front-loaded before the filtering detail.

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 single optional parameter, read-only tool with no output schema, describing the returned fields is exactly what's needed. Only pagination/ordering behavior for large accounts 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 100% and the schema already documents the folder parameter including the '' / '/' top-level convention. The description's parenthetical duplicates rather than extends that, 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?

States a specific verb and resource ('Lists the files in your AIToURL account') and previews the returned fields (public links, download counts, folder). It is distinguishable from list_folders by resource noun, though it never explicitly contrasts with 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?

Explains how to filter ('Pass folder to list only one folder'), which implies the use case of browsing a single folder, but gives no explicit when-to-use vs search_files (for lookup by name) or list_folders (for folder structure). Guidance is implied 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description needn't restate safety. It does add two pieces of behavior beyond the annotations: the Pro-plan gating (a real precondition an agent must handle) and the shape of returned entries (paths plus per-folder file counts). It omits ordering, pagination, and whether folders are flat or hierarchical, keeping it below 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?

A single sentence with no filler; the resource is named first and the returned fields and plan constraint follow immediately. Nothing is redundant with the title or annotations.

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 no input schema and no output schema, the description carries the burden of saying what comes back, and it does so at a high level (paths and file counts). It is nearly complete for a simple read-only list tool, though it leaves folder hierarchy and any result-size limits for the agent to discover.

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 tool takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. The description correctly introduces no parameter concepts that would need explaining.

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 gives a specific verb and resource ("Lists your folders") and adds what each entry contains ("paths and how many files each one holds"), which goes beyond the bare name. It does not explicitly distinguish itself from siblings like list_files or search_files, but the noun makes the resource scope unambiguous.

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 parenthetical "(Pro feature)" signals a plan prerequisite, which is useful context for an agent deciding whether to call it. However, there is no explicit when-to-use versus list_files, no statement about when the tool is not appropriate, and no fallback behavior described if the account is not Pro.

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 openWorldHint=false, so the safety profile is covered by structured data. The description contributes useful behavior beyond that by stating that counts of files and folders accompany each tag, but says nothing about ordering, result size, or whether tags with zero usage appear.

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?

A single sentence with zero waste; the resource and the returned metric are both front-loaded, and nothing is repeated from the title or schema.

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 simple, parameterless read with no output schema, the description gives enough to call it correctly and to know what the response contains. Adding ordering or scope (global vs. workspace) would make it fully self-sufficient.

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 tool takes no parameters (schema coverage 100%, empty properties), so there is nothing for the description to disambiguate. Baseline 4 applies because the absence of inputs is reflected faithfully and no scope arguments are implied.

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 (lists) and resource (tags) and even discloses the payload shape — per-tag file and folder counts — so the agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling update_tags, which is the mutating counterpart on the same resource.

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?

Usage is only implied: a zero-parameter enumeration tool is naturally called to discover what tags exist before tagging or updating. There is no explicit statement of when to prefer this over search_files or update_tags, and no note that the result covers the whole account/workspace rather than a filtered subset.

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 this is a non-destructive, idempotent write, and the description adds genuinely new behavior: the Pro plan gate, automatic creation of missing folders, and the fact that the public link is preserved. The public-link guarantee is exactly the kind of side-effect disclosure an agent can't get from structured fields. It stops short of describing failure modes or what happens when a same-named file exists at the destination.

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?

A single sentence plus a clause conveys the action, the precondition, the auto-creation side effect, the top-level alternative, and the stable-URL guarantee. It is front-loaded with the core action and contains 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 two-parameter, non-destructive, idempotent tool with full schema coverage and no output schema, the description covers plan requirements, folder auto-creation, and a notable side effect. Only edge-case behavior (collisions in the destination, errors for unknown file_id) is absent, which is a modest 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 coverage is 100% and both parameters are already documented, including the '' top-level convention and where file_id comes from. The description restates the empty-string case without adding syntax, path constraints, or format detail beyond the schema, 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 description opens with a specific verb+resource ('Moves a file into a folder') and covers both destination modes, so an agent can immediately tell this is a relocation operation rather than a rename or copy. It never names a sibling tool, but the verb+resource pairing is distinct enough from rename_file or upload_file that confusion is unlikely.

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 supplies a real prerequisite ('Pro plan') and clarifies the empty-string case for returning a file to the top level, which is useful context for choosing this call. However, there is no explicit guidance on when to prefer this over rename_file, replace_file, or create_folder, and no statement about what happens when the file is already in the target folder.

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 meaningful behavior beyond the annotations: the output is a permanent PUBLIC link (a real disclosure about exposure), only text is uploaded, and the supported Markdown subset defines what renders. It does not say whether passing file_id replaces the whole body or merges, nor what the response payload contains — gaps against a mutation tool with no output schema.

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 core action and the sibling comparison, then the capability list, then the Pro-plan update path. The Markdown feature enumeration is long but earns its place by telling the agent what syntax will render; one or two phrases could still be trimmed.

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 an 8-parameter mutation tool with no output schema, the description covers the return value (permanent public link), the plan constraints on optional params, and the alternative to prefer. It falls short on overwrite semantics when file_id is supplied and on any indication of what the tool returns on success versus failure.

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 parameters are already well documented; the description largely restates the file_id update behavior already in the schema. It adds little new per-parameter meaning beyond framing markdown as the only content sent and noting Pro-plan gating, so the baseline of 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: turns Markdown into a PDF on the server and returns a permanent public link. It explicitly distinguishes itself from upload_file for written documents, so an agent can route correctly without opening either 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?

Names the alternative (upload_file) and the condition that selects this tool ('documents you write: guides, checklists, lead magnets, reports'), plus why ('only the text is sent, so it works for long, multi-page documents'). It also gives the Pro-plan condition for using file_id instead of creating a new document.

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 readOnlyHint=false, idempotentHint=true and destructiveHint=false already supplied, the description still earns credit by disclosing three non-obvious traits: the extension is forced from the real content, existing shared links continue to work, and the returned link reflects the new name. It does not cover name-collision behavior or permission requirements, which keeps it below 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 short sentences, front-loaded with the action, then the extension rule, then link-continuity behavior. Every clause carries distinct information and nothing is repeated from the schema or annotations.

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 two-parameter, fully documented, fully annotated tool with no output schema, the description covers the mutation's side effects and even the return value (a new link). Only edge cases such as duplicate-name handling are absent, which is a minor gap at this complexity.

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 file_id and new_name meaning are already documented in the schema and the baseline is 3. The description does add one bit of semantic value by implying the extension portion of new_name is governed by the underlying content, but that is the only supplementation.

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?

"Renames a file" states a specific verb and resource, and the resource noun cleanly separates it from the sibling rename_folder. It stops just short of explicitly naming that alternative, so it is clear rather than maximally distinguishing.

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 parenthetical "(every plan)" gives availability context, which is useful, but there is no explicit when-to-use guidance versus siblings such as replace_file or move_file, nor any stated prerequisites. Usage is implied by the tool's obvious purpose rather than described.

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?

The description adds two behavioral facts the annotations do not cover: the Pro-plan requirement and that public links survive the rename. Combined with idempotentHint=true and destructiveHint=false, an agent has a good picture. It stops short of saying what happens on a name collision or whether the old path becomes invalid.

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 very short sentences: eligibility gate first, action second, side-effect reassurance third. Nothing is wasted and the most decision-relevant constraint 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 two-parameter, non-destructive rename with a fully documented schema and no output schema, the description covers the essentials. Minor gaps remain around error cases (folder not found, duplicate name), which for a metadata mutation would be worth one more sentence.

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 both parameters documented including examples and the explicit note that new_name is not a path. The description adds nothing further about parameters, 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?

States a specific verb and resource ("Renames a folder"), which cleanly separates it from rename_file and other siblings in the list. It is clear about what changes, though it doesn't explicitly contrast itself with the file-renaming sibling.

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?

"Pro plan only" is a genuinely useful eligibility prerequisite that tells the agent when the call will fail. However, there is no guidance on when to use this versus move_file or create_folder, and no mention of preconditions such as the folder needing to exist.

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 flag destructiveHint=true and readOnlyHint=false, so the write/destroy profile is covered. The description adds genuinely new behavioral context the annotations cannot express: a plan entitlement gate ('Pro plan only') and the side effect that shared links survive the replacement, which is the main risk consideration for an agent.

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 tight sentences; the plan restriction is front-loaded, then the effect on links, then the fallback. Nothing is repeated or padded.

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 3-parameter mutation tool with full annotation coverage and full schema coverage, it supplies the non-obvious constraints (plan tier, link stability). It does not mention what the call returns, but no output schema exists and the return is not essential to calling it 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 description coverage is 100% and every parameter, including the optional file_name with its 'omit to keep current name' guidance, is documented in the schema itself. The description adds no parameter-level detail beyond that, 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 description states a specific verb and resource ('Replaces the content of an existing file') and adds the distinguishing trait that the public link is preserved. That differentiates it in effect from upload_file and publish_document, though those siblings are never named, so the routing is implicit 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?

It gives a clear when-to-use condition (Pro plan, existing file, link must keep working) and an explicit when-not/alternative path for Free plan users ('publish a new file instead'). The gap is that the alternative is described as an action rather than pointed at a concrete sibling tool such as publish_document or upload_file.

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 openWorldHint=false, so safety is covered. The description still adds real behavioral detail beyond them: matching is typo-tolerant and matching folders are included in the result set. It does not describe result ordering or result shape, but limit/sort defaults are carried by the schema.

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, no filler: the matching criteria and filters come first, the usage guidance second. Every clause carries information an agent cannot get from the name alone.

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 six-parameter, entirely optional, read-only search tool with no output schema, the description covers what is matched, the filter dimensions and the fact that folders appear in results. Return shape and pagination behavior beyond limit are left unstated, which is a minor gap rather than a blocking one.

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?

With 100% schema description coverage, the schema already explains every parameter, including the constraints on query, tags, folder, type, sort and limit. The description adds only one nuance beyond the schema — that query matching tolerates typos and can be omitted to filter only — so it sits at the baseline rather than above it.

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 ('finds files') and enumerates what is matched: name, folder name or path, and tags, plus optional media-type/tag/folder filters. It is clearly distinguishable from a plain lister such as list_files, though it never names a sibling tool explicitly, which keeps it 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?

It gives a concrete when-to-use scenario with example queries ('the Dupont quote', 'my latest video') and a downstream intent ('before sharing its link'). It stops short of an explicit exclusion, e.g. 'to browse everything without a keyword, use list_files instead', so the agent must infer the boundary.

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 non-destructive, idempotent, closed-world mutation; the description adds genuinely new behavioral context: adding tags requires a Pro plan while removing works on every plan, and tags are normalized to lower-case with spaces converted to dashes. What is missing is failure behavior (e.g. what happens if both file_id and folder are supplied, or if neither is).

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 dense sentences with zero filler, front-loaded with the plan constraint, then targeting, then operation selection, then tag formatting. Every sentence carries information an agent would otherwise lack.

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 5-parameter mutation tool with no output schema and no annotation coverage of correctness rules, the description supplies the entitlement, targeting, mode-selection and normalization rules the agent needs. The one gap is that required parameters are empty in the schema, so the description's 'target a file with file_id or a folder with folder' implies a requirement without confirming what happens if neither is passed.

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 60% and the two undocumented arrays are exactly the ones the description explains: 'add' and 'remove' change some tags, 'set' replaces them all. It also clarifies the file_id-vs-folder targeting choice and the tag string normalization rules that the schema does not encode. Only the mutual exclusivity or requiredness of the target parameters remains unstated.

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 the resource (tags on a file or a folder) and the three operations it bundles (add, remove, set), plus how to target each resource type. It is clear enough to act on, though the verb 'update' is only spelled out indirectly through the explanation of add/remove/set rather than a single declarative 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?

Explicitly tells the agent which parameter mode to pick: 'Use add / remove to change some tags, or set to replace them all.' It also states the plan restriction up front. It does not differentiate from sibling tools such as list_tags (read) or mention when not to use it, so it stops short of the top band.

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: it discloses the ~100 KB size ceiling, that the resulting link is permanent and public, that base64 handling is 'very slow' for large inputs, and that the real file type is detected from content rather than trusted from the name. Annotations only cover the mutation/open-world profile, which this description does not contradict.

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 size limit and the routing alternatives are front-loaded in the first two sentences, and the allowed-type list is long but earns its place because unsupported types would fail the call. The media-type enumeration is the only portion that pushes toward verbosity.

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 no output schema, the description correctly states the return value (a permanent public link) and covers size, encoding, and type validation. It does not say what happens on a name collision or whether the link can be revoked, which matters given idempotentHint=false and the public exposure of the result.

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 genuinely new meaning: content_base64 is constrained to small payloads, the file must be sent base64-encoded, and 'the real type is detected from the content' tells the agent that the extension in file_name is not authoritative. It doesn't address the Pro-plan scope of tags/folder, but that is already documented in 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 and resource ('Uploads a SMALL file ... sent as base64') plus the outcome ('returns a permanent public link'). It explicitly distinguishes itself from create_upload_link (fallback) and publish_document (for documents you write), so an agent can route correctly without opening sibling schemas.

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 explicit when-to-use ('when a direct upload via create_upload_link failed or isn't possible and the file is small'), explicit when-not ('Never use base64 for files over ~100 KB ... give the user the create_upload_link page instead'), and names the alternative for a neighboring case ('For documents you write, use publish_document').

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