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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the endpoint path and a terse 'Returns a confirmation,' but omits the consequence of a name collision (overwrite vs. error) and any permission requirements — useful gaps given the idempotentHint.

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 one-line purpose followed by a clean per-parameter list; every line carries information and there is no filler. The args block slightly duplicates the schema but remains scannable.

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 mutating create tool with no output schema, the description covers inputs well and notes a confirmation return, but leaves conflict/overwrite behavior and directory-vs-file edge cases (e.g., content ignored for directories) unexplained. Annotations carry the safety burden, so this is adequate but not 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 description coverage is 100%, so the schema already documents all five parameters; the baseline is 3. The description adds concrete example values ('notes.md', 'chapters') that clarify intent, but nothing about formats or constraints 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 and resource ('Create a new text file (or directory)'), plus the target project and HTTP endpoint. However, it does not differentiate itself from the sibling litewrite_write_file, so an agent must infer that 'create' means new-file-only versus updating existing content.

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

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

The word 'new' implies creation-only usage, but there is no explicit when-to-use guidance, no mention of prerequisites (e.g., project must exist), and no routing versus the nearest alternative, litewrite_write_file. The agent is left to infer the distinction.

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 non-idempotent, but the description adds two genuinely new facts: the operation is irreversible (no undo/trash) and it also removes directories, not just files as the name/title suggest. It does not describe failure modes 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 compact sentences, front-loaded with the operation and immediately followed by the endpoint and the irreversibility warning. 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 destructive tool with no output schema and annotations that already cover the safety profile, the description supplies the key extra facts (directory deletion, irreversibility). Only the absence of any recovery/permission context keeps it from being fully 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 description coverage is 100%, so filePath and projectId are already documented in the schema. The description adds nothing about path resolution or project scoping, 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 (delete) and resource (file or directory) within a named product, and adds the underlying endpoint. It is clearly distinguishable from siblings like read_file, write_file, and rename_file, though it does not explicitly name what it is not.

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 by the operation itself and the caution that deletion is irreversible, which signals 'be certain before calling.' There is no explicit when-to-use guidance or mention of alternatives such as rename_file for non-destructive reorganisation.

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, open-world behavior, so the safety bar is covered. The description adds useful behavior beyond them: what is returned ({path, type, size?}) and that recursive defaults to true. It does not mention pagination or limits on large trees, which is the only notable 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?

Front-loaded with the purpose, then a compact Args block and a one-line return note. Structure is scannable and earns its place; the Args list partially restates schema descriptions but stays brief.

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, but the description compensates by describing the return shape. Annotations, schema, params and return format are all covered; only pagination/scale behavior on large projects is unaddressed.

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 baseline is 3. The description goes beyond the schema by naming the source of projectId (litewrite_list_projects) and giving a concrete example value for directory ('chapters'), adding context the schema lacks.

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 directories in a Litewrite project') plus the backing endpoint. It cross-references litewrite_list_projects for the required id, but does not explicitly distinguish itself from the sibling litewrite_local_list (remote vs local listing), so sibling differentiation is only partial.

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: you call it to enumerate a project's files, and the agent is told to get projectId from litewrite_list_projects. There is no explicit when-not guidance or comparison against local listing alternatives, so this is minimum-viable routing rather than full 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 and openWorld, so safety is covered. The description adds genuinely useful context beyond them: the actual HTTP endpoint is a POST despite being a read operation, plus owner defaulting behavior (LITEWRITE_OWNER_ID or 'default'). Auth requirements and rate limits remain unstated.

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 sentence, then usage, then args, then return shape — a clean, scannable order with no filler prose. The Args section does duplicate what the schema already states, which is mildly redundant but not costly.

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 present, the description carries the return contract itself and does so precisely: an array of projects with id, name and optional description/mainFile/compiler/timestamps. Combined with the endpoint and owner-default behavior, an agent has everything needed to call and consume this 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 the schema already documents all three parameters including the default 50 and the owner fallback. The Args block largely restates those same facts (the 1-200 range is already encoded as minimum/maximum), adding no new syntax or format detail. 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 ('List projects available in the Litewrite platform') plus the underlying endpoint, and the usage line scopes it to discovering a projectId, which separates it from the file-oriented siblings. An agent can tell it apart from litewrite_list_files and litewrite_local_list 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 says when to use it: 'discover a projectId before pulling or reading files.' That gives clear context, but it names no alternative or exclusion — notably it never distinguishes itself from litewrite_local_list, which also enumerates projects/files and could plausibly be chosen instead.

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, and non-open-world, so the safety profile is covered. The description still adds real value beyond them: it confirms no network call is made, discloses the on-disk path, and states the return shape. It omits failure behavior when the mirror directory is absent.

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 statement in the first sentence and keeps the whole definition short. The explicit Args block is largely redundant given 100% schema coverage, which is the only minor waste.

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 compensates by stating the return value (relative file paths), and annotations cover the safety profile, so the agent has what it needs to call it. The one gap is precondition behavior when no local copy has been pulled yet.

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% for the single projectId parameter, so the schema already carries the meaning. The description's Args block merely restates the same type/required/meaning with no added syntax or constraint detail. 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 ("List the files in the local mirror of a project") plus the decisive scope qualifier "(no network call)", which cleanly separates it from the remote sibling litewrite_list_files. An agent can identify what this does 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?

Gives clear context by naming the concrete location (~/.litewrite-mcp/<projectId>) and tying the tool to the litewrite_pull/push/status workflow, which implies when it is useful. It never explicitly says when to prefer this over litewrite_list_files or what to do if the local copy does not yet exist, 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, and non-destructive, so the safety profile is covered. The description adds value beyond that: it discloses there is no network call, the on-disk location (~/.litewrite-mcp/<projectId>), and the return format (raw bytes framed as text). Missing only things like error behavior on a missing file.

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 core statement, then the sibling contrast, then a compact Args block and return note. Every line earns its place with no filler.

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

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

For a two-param local file read with no output schema, the description covers location, behavior, args, and return framing. It omits error/missing-file behavior and whether the local copy must first be pulled, which a careful agent might want.

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 schema already documents both parameters with the same wording ('Relative path in the local copy', 'The Litewrite project id'). The path-location note adds slight context for projectId but no new syntax or constraints beyond the schema, so baseline 3 is appropriate.

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 (local working copy file) and explicitly contrasts with the sibling litewrite_read_file. An agent can distinguish local vs remote reads 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?

The '(no network call)' note and the direct contrast with litewrite_read_file give clear context for when this tool applies. It does not spell out an explicit when-not or a full decision rule against the other read/list siblings, but the local-vs-remote distinction 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 idempotentHint=true and destructiveHint=true, so the description does not need to re-state overwrite risk. It adds genuinely new behavioral context the annotations cannot convey: the write is local-only with no network call, and it is deferred until litewrite_push. It does not clarify whether a nonexistent path or missing directories are created.

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 and the no-network qualifier, then a well-formatted Args block. Mild redundancy: the deferred-upload point is made twice ("Changes are NOT uploaded... until litewrite_push" and "will be uploaded by litewrite_push"), and the Args repeat 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 three-param mutation with no output schema and annotations that already cover safety, the description supplies the essential missing piece: the local-staging/push workflow. Edge cases such as path creation or failure modes on unwritable paths are unaddressed but minor.

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 three parameters are already documented. The description's Args block largely restates the schema; the only added nuance is "the full text content to write," implying replacement rather than append. Baseline 3 is appropriate when the schema carries the load.

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 or overwrite a file") and scopes it precisely to "the local mirror of a project (no network call)". This distinguishes it cleanly from remote-write siblings like litewrite_write_file and litewrite_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?

Gives clear workflow context: changes are NOT uploaded until litewrite_push runs, which tells the agent this is a staging step rather than a publish step. It stops short of explicitly naming the alternative tool to use for remote writes, so the local-vs-remote routing 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?

Description discloses significant traits beyond annotations: the exact local target path and env override, that it deletes local files no longer on the server, and that it writes a content manifest. The destructive-looking local deletion is tempered by the destructiveHint=false annotation, but the description appropriately warns about the local removal behavior. It could note whether server-side content is ever modified.

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 single-sentence purpose, then scoped behavioral detail, then an Args block and a Returns line. No wasted sentences; each clause adds operational value.

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 mirror tool with no output schema, the description covers target location, deletion semantics, and manifest recording. The 'Returns what was downloaded and removed' line partially covers output given no output schema. Could mention auth requirements or behavior when the local dir 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% and there is only one parameter, so the schema fully documents projectId; the description adds nothing beyond restating it as required. 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 (mirror/download) and resource (Litewrite project into a local directory), and explicitly frames it as git-clone/pull style, which distinguishes it from siblings like litewrite_read_file or litewrite_list_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?

The git-clone/pull framing gives clear operational context and the manifest note implies pairing with litewrite_push, but it never explicitly names when to use this versus litewrite_pull vs. granular read tools, nor states prerequisites like authentication or a valid projectId existing locally.

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, readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them by spelling out the mechanism: new/changed files uploaded, removed local files deleted server-side, and the manifest refreshed — an agent learns precisely what gets destroyed and why the operation is idempotent.

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 mechanism, then the prerequisite, then args and return. Every sentence earns its place, though the args block restates the 100%-covered schema field and is slightly 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?

For a single-parameter mutation with no output schema, the description covers the mechanism, the deletion side effect, the prerequisite tool, and a rough outline of the return value. Missing only edge-case behavior such as conflict resolution, which is a minor gap given the annotations.

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% for the single projectId parameter, so the schema already carries its meaning. The description merely restates 'projectId (string, required): The project id', adding no format or source detail beyond it, which pins this at the baseline of 3.

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 local working-copy changes back to Litewrite — and the 'git-push style' analogy plus the explicit mirror-vs-manifest comparison distinguish it from siblings like litewrite_pull and litewrite_write_file. An agent can tell what this does 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?

Explicitly routes the agent to litewrite_status first to preview changes, which is a concrete prerequisite. It stops short of naming when NOT to use it (e.g. versus litewrite_upload_file for single-file uploads), so it is clear context without full alternative coverage.

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 safety profile is covered. The description adds genuine value beyond them: the underlying endpoint, the server-vs-local-mirror preference, and the UTF-8 return format.

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 the sibling disambiguation, then a compact Args block. The Args list mildly duplicates the schema, so it is not maximally tight, but nothing is wasted.

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 supplies the return format (UTF-8 text) and the source-of-truth behavior. Edge cases like out-of-range line values are not addressed, but everything needed to call the tool correctly is present.

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 concrete path examples ('main.tex', 'chapters/intro.tex') and clarifies that startLine/endLine read a line range, which is marginally more than the schema's terse field descriptions.

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

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

States a specific verb+resource ('Read the content of a file') and explicitly distinguishes itself from the sibling local reader, naming litewrite_local_read and the condition that selects 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?

Gives explicit when-to-use routing: prefer the server copy, and use litewrite_local_read to read the local working copy instead. The alternative and its selection condition are stated, not implied.

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, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and the 'keeps the same parent' nuance for rename vs. full-path move, but says nothing about failure modes such as name collisions, a missing sourcePath, 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?

Front-loaded one-line purpose followed by a compact parameter list; nothing is wasted. The arg list partially duplicates the schema, which costs it a point, but it is short and easy to scan.

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 four-parameter mutation tool with a fully described schema and no output schema, the entry covers purpose, endpoint, and the key parameter-selection rule. The main gap is behavioral edge cases (overwrite on collision, error when source is absent), which is minor given annotation coverage.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a cross-parameter constraint not present in the schema: at least one of newName or targetPath must be supplied. It also clarifies that newName preserves the parent directory while targetPath relocates the file.

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 (rename/move) plus the resource (file/folder) and even the backing endpoint (POST /api/internal/files/rename). This is clearly distinguishable from siblings like litewrite_write_file, litewrite_create_file, and litewrite_delete_file.

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 genuine rule for choosing between the two optional parameters ('Provide at least one of newName or targetPath'), which is real usage guidance. However, it offers no tool-level when-to-use context against siblings (e.g., move vs. delete+create, or when to prefer litewrite_write_file) and no 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description still adds genuine value beyond them: it defines the comparison baseline (last pull/push) and enumerates the result kinds (added/modified/removed/remote_new), which the annotations cannot express.

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 comparison concept in sentence one, then adds usage and returns in labeled sections. The Args block is mildly redundant given the schema, but the structure is scannable and every other sentence earns its place.

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, so the description carries the burden of describing the return value and does so adequately (a list of changes with kind tags). Combined with the stated read-only, non-mutating behavior and the comparison baseline, an agent has everything needed to call and interpret this 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?

Only one parameter exists and schema description coverage is 100%, so the schema already documents projectId as 'The Litewrite project id'. The description restates it ('projectId (string, required)') without adding format or lookup guidance, 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 — comparing the local mirror against Litewrite — with a concrete analogy ('git-status style') and a scope qualifier ('without changing anything'). This distinguishes it immediately from litewrite_pull and litewrite_push, which actually move data.

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 clear decision context: 'Use it before deciding whether to push local changes or pull remote ones,' which implicitly routes to the push/pull siblings. It does not explicitly state when not to use it or name those siblings by name, so it falls just 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 destructiveHint=true, openWorldHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it may create OR overwrite, overwrite defaults to false, and the endpoint is disclosed. It does not mention auth requirements or what happens on failure, keeping it short of 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?

Front-loaded with purpose, endpoint, and usage nuance before the argument list, which is easy to scan. It loses a little by restating schema field descriptions nearly verbatim in the Args block, but nothing is padded or out of order.

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, the description covers purpose, endpoint, the create-vs-overwrite behavior, the source-content exclusivity rule, and the return ("a confirmation"). Nothing an agent needs to call 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 baseline would be 3. However, the description adds a genuinely useful constraint absent from the schema: "provide exactly one source" for content vs contentBase64, which the flat schema with additionalProperties=false cannot express. It also clarifies filePath is relative ("figures/logo.png").

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+resource ("Upload a file to Litewrite, creating or overwriting it") and explicitly positions it against siblings: for binary assets "where edit/create are unsuitable, or as an alternative to create." An agent can route between upload_file, create_file, and write_file from the description alone.

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 a clear use condition (binary assets such as images and PDFs) and names an alternative (create). There is no explicit when-not guidance, e.g. that text files should use write_file/create_file instead of this tool, 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by clarifying the 'full content' replacement semantics (no merge/append) and that the file must already exist, plus the endpoint. It stops short of explaining failure modes when the file is absent, so a 4 rather than 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?

Front-loaded with the core action, then alternatives, then args, then return value – a sensible ordering. It is appropriately sized, though the Args list duplicates the 100%-covered schema, which is minor 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?

No output schema exists, and the description states 'Returns a confirmation,' which is thin but adequate for a write tool. Combined with annotations covering the safety profile and clear sibling routing, the definition is nearly complete; only error/failure behavior when the target file is missing is unaddressed.

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 schema already documents all three parameters with descriptions and types. The Args block in the description merely restates the schema without adding format, path, or content semantics. Baseline 3 applies when 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?

The description states a specific verb and resource ('Replace the full content of an existing file') and even names the endpoint. It distinguishes itself from siblings by specifying the 'existing file' constraint and routing new files to litewrite_create_file. An agent can identify exactly what this tool does and does not do.

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 alternatives with conditions: use litewrite_create_file for brand-new files and litewrite_upload_file for binary files. This is genuine when-to-use/when-not guidance rather than implied context, leaving nothing to inference.

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