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

Annotations already declare this is a mutating, non-idempotent, non-destructive, open-world operation, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the pre-existence failure mode, which explains why idempotentHint is false. It stops short of saying what happens if the parent folder is missing, whether folder creation is recursive, or how the failure is reported.

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 core sentence and the sibling redirect come first, with examples placed after as optional illustration. Slight redundancy: the examples largely re-encode what the schema descriptions already say, so they consume space without adding much new signal.

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 creation tool with no output schema and annotations that already cover mutation safety, the description supplies the essential missing piece: the collision-failure rule. Minor gaps remain around parent-directory behavior and error surfacing, but nothing an agent needs to invoke it correctly is absent.

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 both parameters are documented, including the required site-folder path format and the boolean meaning of is_folder. The description's examples restate essentially the same information (folder vs. empty file) rather than adding new semantics such as path normalization or trailing-slash behavior.

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 ('Create a new empty file or a new folder on your Nekoweb site') and immediately delimits scope with 'empty', which is what separates it from the write_file sibling. An agent can distinguish it from nekoweb_write_file and nekoweb_upload_file 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 alternative and the condition that selects it: 'To create a file with content in one step, use nekoweb_write_file instead.' It also gives a when-not condition ('Fails if something already exists at that path') and two worked examples mapping natural language to arguments.

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 and idempotentHint; the description adds real value beyond them by emphasizing permanence ('This cannot be undone') and disclosing that deleting a folder is recursive. It does not cover permission requirements or error behavior, which keeps 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?

Two short, front-loaded sentences plus a single example; every line earns its place. The irreversibility warning is placed immediately after the core action statement.

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 annotations covering the safety profile and full schema documentation, nothing an agent needs in order to call it correctly is missing. No output schema exists, and none is needed for a delete operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the path format and constraints are already fully documented in the schema. The description's example path reinforces that convention but adds no new syntactic or semantic detail, matching the baseline for high-coverage schemas.

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 ('Permanently delete a file or a folder') plus scope ('from your Nekoweb site'). It is clearly distinguishable from read/write/move/upload siblings, and the recursion detail ('including everything inside it') removes ambiguity about folder semantics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete usage example ('Remove the old drafts folder' -> { path: ... }) that shows the calling context. It does not name alternatives or explicitly state when not to use it (e.g., use nekoweb_move for relocating), so it falls 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 readOnlyHint, idempotentHint, destructiveHint=false, so the safety profile is covered. The description adds real behavioral content beyond them: what each bucket covers, the 95MB threshold that separates 'big_uploads' from 'general', and that counters carry max/remaining/reset. It doesn't mention window lengths or whether limits are per-account or per-IP, which would have completed the picture.

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 paragraphs: purpose and bucket taxonomy first, then what the payload contains and when to call. Every sentence carries information (the 95MB threshold and the 429 trigger are both actionable), with no filler or repetition of the 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?

With no output schema, the description still tells the agent what comes back — three named limit buckets, each with maximum, remaining, and reset time — which is exactly what an agent needs to reason about backoff. For a zero-required-parameter read 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?

There is a single optional parameter, response_format, and the schema description already covers it at 100% with an enum and default. The description adds no meaning about the parameter 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 gives a specific verb and resource ("Show the account's current API rate limits") and then enumerates the three buckets returned ('general', 'big_uploads', 'zip'). No sibling tool touches rate limits, so an agent can distinguish this from the file/site CRUD siblings immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states concrete triggering conditions: call before bulk operations or after a 429 error. That is clear usage context that maps well to the bulk siblings (nekoweb_upload_file, nekoweb_import_zip). It does not explicitly name those siblings or state a when-not case, so it stops just short of the top.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavioral facts. Most notably, it discloses that lookups with 'site' require no API key and reach outside the caller's account, which is the key operational nuance for an open-world read.

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 returned fields, followed by the two-mode behavior, then compact examples, then a pointer to the sibling tool. Every line carries distinct information and 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?

There is no output schema, but the description compensates by listing the returned fields, and it covers auth requirements, both calling modes, and the alternative tool for enumeration. An agent has everything needed to select and invoke this 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 both parameters are already documented, but the description adds the semantic distinction that matters most: omitted 'site' means the authenticated user's own site while a supplied domain means a third-party public site. The examples reinforce the format expected (a bare domain). 'response_format' is left to the schema, which is acceptable at full coverage.

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 and resource ("Get a Nekoweb site's") and enumerates the exact fields returned: title, domain, views, followers, update count, and creation/update dates. It also clearly separates the two modes (own site vs. any public site), which is enough to distinguish it from siblings like nekoweb_list_sites.

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 explicitly when to omit 'site' (returns the configured key's site) and when to pass it (any public Nekoweb site, no API key needed), then reinforces this with two concrete input examples. It also names the alternative tool, nekoweb_list_sites, for enumerating all sites on an account.

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 destructive=true, idempotent=true and openWorld=true, so the safety profile is covered; the description adds the key operational detail that extracted files overwrite existing files at the same paths and warns that the 'zip' rate limit is often one import per period. This is real behavior beyond the annotations, though it says nothing about failure modes or whether the target folder must already exist.

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 operation and overwrite semantics, then the rate-limit warning, then an example. All three blocks carry information, with only minor redundancy between the example and the schema descriptions.

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 destructive, open-world mutation with no output schema and no required parameters, the description covers overwrite semantics and rate limiting but omits what a reasonable agent still needs: that one of the two zip sources is mandatory, whether the folder is created if absent, and what a success or partial-extract result looks like.

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 folder, zip_base64 and zip_local_path are already documented in the schema; the description's example only illustrates one combination of them. It does not clarify the meaningful ambiguity that zero parameters are required, i.e. that at least one of zip_local_path or zip_base64 must be supplied.

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 ('Upload a .zip archive and extract it into a folder of your Nekoweb site') and adds the distinguishing intent 'to deploy a whole site at once', which separates it from the single-file sibling nekoweb_upload_file without naming it directly. An agent can identify the operation, though an explicit sibling callout would make it airtight.

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 a concrete intent-to-call example ('Deploy my built site') and an explicit prerequisite: check nekoweb_get_limits first because the 'zip' rate limit is strict. It lacks an explicit negative case (e.g. 'for a single file use nekoweb_upload_file instead'), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description adds genuinely new behavior: recursion costs one API request per subfolder and is capped at 25 per call, and results are paginated via limit/offset. It does not explain what the output looks like or what happens when the cap is hit, leaving minor gaps.

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 action, then recursion/pagination behavior, then two compact intent examples. No filler sentences, though the example block adds some length beyond the essentials.

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?

Six optional parameters with full schema descriptions, no output schema, and a read-only safety profile already covered by annotations. The description supplies the recursion cost and pagination context an agent needs; only the shape of returned entries is left implicit, which is acceptable without an output schema.

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 beyond it: recursive interacts with max_depth as 'levels to descend' and carries a per-subfolder rate-limit cost, and limit/offset are framed as pagination. Only response_format goes unmentioned outside 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 ('List the files and folders inside a folder of your Nekoweb site') plus the ordering ('sorted by path'). An agent can distinguish this from siblings like nekoweb_read_file or nekoweb_list_sites 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?

Concrete examples map user intents ('What's on my site?', 'Find every image') to parameter sets, which gives clear when-to-use context. It does not explicitly say when not to use it or name an alternative sibling for related operations, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the scoping rule (only sites owned by the API key), the fact that the main site is marked, and the shape of the returned dataset including the folder field. It stops short of noting pagination or result-size behavior for accounts with many sites.

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: what it returns first, then how to use the result, then the alternative. Every sentence carries distinct information and the most actionable guidance (the folder path) 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?

No output schema exists, and the description compensates by enumerating the returned fields, which is the main thing an agent needs to decide whether to call it. Combined with the read-only annotations and the fully documented single parameter, nothing material is missing for a simple list 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?

There is a single optional parameter, response_format, and schema coverage is 100% with an enum and a default already documented in the schema. The description says nothing about it, so it neither adds nor contradicts meaning — the baseline 3 applies when the schema does all the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List every site on the Nekoweb account that owns the API key") and enumerates exactly what each entry contains: domain, title, views, followers, dates, and file folder. It also distinguishes itself from the sibling nekoweb_get_site_info by name, so an agent can tell the two apart 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?

Gives an explicit sequencing instruction ("Call this first to learn the folder to use in file paths") with a concrete example path, and names the alternative for the single-site case ("Use nekoweb_get_site_info for a single site"). Both when-to-use and when-to-use-something-else are covered.

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, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the parent-folder existence requirement, but for a destructive operation it omits key behavior: whether an existing destination is overwritten, what happens to a folder's contents when moved, and whether the move is reversible or cross-site.

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 plus two compact examples, with the core action statement front-loaded ahead of the precondition and illustrations. Every line adds usable information; nothing is redundant with 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?

With only two parameters, a full schema, and annotations covering safety, the description supplies essentially everything needed to construct a call correctly. The remaining gap is return/error behavior and overwrite semantics, which matter somewhat given destructiveHint=true but are not blocking for invocation.

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 above that by specifying that both paths are absolute from the site root and by demonstrating real path formats (e.g., '/mysite.nekoweb.org/images/logo.png') that the schema's generic 'Current path'/'New path' wording does not convey. It does not clarify path separator or trailing-slash conventions for folders.

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 ('Rename or move a file or folder on your Nekoweb site'), which is clearly distinct from siblings like nekoweb_write_file, nekoweb_create, and nekoweb_delete. The two worked examples reinforce the exact semantics of a combined rename/move operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete precondition ('the destination's parent folder must exist') and clarifies path basis ('full paths from your file root'), with examples mapping natural-language requests to calls. It lacks explicit when-to-use-vs-alternatives guidance, e.g. no note telling the agent to use write_file instead when changing content rather than location.

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 establish a safe, idempotent read, and the description adds substantial behavior beyond them: SSI directives are not rendered, text is paginated, images up to 5.0 MB are returned as images, and other binaries return only size.

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?

It front-loads the core raw-source behavior, then compactly explains file-type-dependent returns and provides two useful examples. Every sentence contributes to selecting or correctly invoking the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter read tool with full annotations and no output schema, it explains return behavior by file type, pagination via offset, SSI handling, and binary size reporting. An agent has enough information to call it correctly in typical cases.

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 path, offset, and max_chars are already well documented in the input schema. The description reinforces offset usage through the 'Read the rest' example, but adds little syntax or constraint detail beyond what the schema provides.

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, 'Read', and resource, 'raw source of a file on your Nekoweb site', while clarifying the important SSI behavior. It is clearly distinguishable from sibling write/delete tools without needing schema inspection.

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 examples give concrete when-to-use context, including continuing a paginated read with offset. However, it does not explicitly name alternatives or when-not conditions, such as using list_folder to discover paths.

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 already declare destructiveHint=true and idempotentHint=true, but the description adds the concrete consequence: existing files with the same name are overwritten. It also discloses the automatic chunked big-file path above 95MB, which is invisible in the schema. Auth requirements and post-upload return behavior are not covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and overwrite warning, then the two input modes, then a sibling pointer, then examples. Every sentence carries information the schema does not, and the examples resolve the local_paths-versus-files ambiguity directly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter mutation tool with no output schema, the definition covers mode selection, overwrite semantics, size handling, and the requirement that the destination folder already exist. It does not describe what the tool returns or the per-call item limits, leaving a small gap given there is no output schema to fall back on.

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 would be 3, but the description adds real meaning: local_paths are files on this machine, base64 'files' is an alternative or complement (the and/or relationship), and the examples show concrete folder/name shapes. It does not restate per-item constraints, 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 (upload files of any type into a Nekoweb site folder) and immediately names the sibling it is not for plain-text content. An agent can distinguish it from nekoweb_write_file 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?

Explicitly routes plain-text content to nekoweb_write_file and gives two worked examples mapping natural-language requests onto the two input modes. It does not address when to prefer nekoweb_import_zip or nekoweb_create for bulk/creation scenarios, which is the one remaining routing gap among siblings.

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, idempotentHint=true and readOnlyHint=false, and the description is consistent with that while adding real context the annotations cannot convey: the whole file is replaced with no partial update, and a create_or_overwrite call fails if the parent folder is absent. It stops short of auth/scoping or rate-limit behavior, so it is strong but not exhaustive.

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 action and the destructive full-replace warning, followed by mode rules, the cross-tool pointer, and two compact worked examples. Each sentence carries distinct information and nothing is repeated verbatim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter, two-required write tool with no output schema, the description covers overwrite risk, mode failure conditions, the prerequisite of an existing parent folder, and the correct sibling for non-text writes. An agent has everything needed to call 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?

With 100% schema coverage the schema already documents all three parameters, including the mode enum values and the path example. The description restates mode behavior and the complete-content rule in slightly different words rather than adding new semantics, so it stays at the baseline rather than earning extra credit.

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 ("Write text content to a file") plus the exact write semantics: creates or fully replaces. It distinguishes itself from nekoweb_upload_file (binary/local files) and nekoweb_create (parent folders) by name, so an agent can route correctly without opening another 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 separates the two modes and their conditions: create_or_overwrite uploads regardless of existence, edit_existing only touches existing files. It also gives when-to-use alternatives in both directions -- nekoweb_create for the missing parent folder, nekoweb_upload_file for binary, nekoweb_read_file before editing a known file -- and closes with two concrete request examples.

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