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

Goes well beyond the readOnlyHint/openWorldHint annotations: halts at first error, build artifacts written outside the clone so they are never pushed, only the log is returned (never a PDF), missing latexmk/TeX is reported rather than silently failing, 180s default timeout reported as error, and sparse-checkout files are restored so figures exist on disk. This is unusually rich behavioral disclosure for a compile tool.

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 purpose and sequencing before diving into fallbacks and environment caveats, and nearly every clause carries distinct information. It is a dense single paragraph that could be broken into structure, but little 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?

No output schema exists, and the description compensates by specifying what comes back (the log only, no PDF) and what a timeout or missing TeX distribution yields. With only two optional params, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning the schema lacks: the ordered fallback list (main.tex, paper.tex, manuscript.tex, root.tex, thesis.tex, article.tex, then the shallowest .tex) and the failure condition when the guess has no \begin{document}.

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

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

Opens with a specific verb and resource ('Compile one project locally with latexmk -pdf') plus the outcome ('report the errors and warnings'), and names the sibling it precedes (push_changes). An agent can distinguish it from sync_project, project_status, or edit tools 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?

Explicit sequencing: 'Call it after editing and before push_changes,' and the scope exclusion 'It compiles the clone as it stands... without pulling' implicitly directs pull/sync work to sync_project. Both when-to-use and what it does not do are stated.

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

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

Adds rich context beyond the annotations: removal is local-only until push_changes, is reversible via discard_local_changes, runs a pull first, refuses directories, still deletes sparse-checkout files, and returns a not-in-project message deleting nothing. Annotations cover destructive/openWorld; the description carries the real behavioral burden and does it well.

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 its local-only scope, then layered with undo, sibling routing, safety warning, and return behavior. Slightly dense and long, but each sentence carries distinct 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 destructive mutation with no output schema, it covers scope of effect, reversibility, publishing dependency, preconditions, edge cases (directories, sparse checkout, missing path), and return behavior. Nothing an agent needs to call safely 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 already documents path (relative to project root, directories refused) and the project selector. The description reinforces 'relative to the project root, as list_files prints it' but adds no syntax or format detail beyond the schema. 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+resource (delete a file from the project) and immediately scopes the semantics: local clone only, latent until push_changes. The 'To replace a file's contents instead, use write_file' clause distinguishes it from the nearest 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?

Gives a clear precondition (confirm the file is unused via search_project on path or label) and names alternatives (write_file to replace, discard_local_changes to undo, show_diff to inspect). No explicit when-NOT-to-use framing, but the routing to siblings is strong.

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 idempotentHint=true, but the description adds non-obvious behavior: it fetches Overleaf first, the discarded work 'cannot be recovered from this server', the reset is scoped to one project, and it returns discard counts. That is meaningful context beyond the annotation flags.

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 destructive action and its scope, then prerequisites and the push_changes use case; each sentence carries distinct, load-bearing information with no filler.

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

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

Covers the key gaps for a destructive no-output-schema tool: irreversibility, scope, prerequisite, and a summary of the return value. Slightly less complete on failure modes (e.g., what happens if the fetch or reset fails mid-way), but otherwise sufficient to call 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 the single 'project' parameter is fully documented in the schema (address, id, or name, with a default). The description only adds scoping semantics ('Only the chosen project is reset'), so the baseline 3 for schema-complete params 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 destructive verb and resource ('permanently throw away every local edit, new file and unpushed commit in one project's clone') and clarifies the resulting state ('clone ends up matching its current version'). An agent can distinguish it from siblings like delete_file or push_changes 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?

Explicit preconditions ('Call show_diff first', 'only call this once the user has said the work should be abandoned') and an explicit use case ('after push_changes refuses a conflicting change'), naming the siblings involved. This is exactly the when/when-not guidance the dimension asks for.

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 flag it as destructive/non-idempotent/open-world; the description adds substantial behavior beyond that: exact section-boundary semantics (heading to next same-or-shallower heading, never swallowing \end{document} or the bibliography), the requirement that newContent start with the sectioning command, Overleaf-pull-then-local-edit ordering, and the no-match fallback of listing titles. This is exactly the behavioral context annotations cannot 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-loaded with the core action and dense with no filler, but the single paragraph is long and packs boundary rules, parameter contracts, and return behavior into one run-on block. Slightly more structure would improve scanability.

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 explains the return (heading replaced and former line range) and the no-match behavior, and it discloses the Overleaf-pull/local-edit/push workflow. Nothing needed to invoke this destructive edit safely 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 is 3, but the description adds genuine semantics beyond the schema: exact-match-wins-then-first-containing-heading-in-document-order for sectionTitle, and the line-for-line replacement contract plus newline requirement for newContent. Only slight repetition of what the schema already states keeps it from a 5.

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 (replace/rewrite) and resource (one whole section of a .tex file, located by title), and explicitly distinguishes itself from the sibling replace_text for smaller changes. An agent can tell exactly what this does versus the other edit tools without opening a 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 ('Use replace_text for a smaller change and this to rewrite a section wholesale') and the condition that selects each. It also routes the follow-up publishing step to push_changes, so the whole workflow is 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 only declare readOnlyHint and openWorldHint; the description adds the crucial implicit network behavior (pulls latest Overleaf commits first), the sparse-checkout caveat that off-disk files are still listed, the untracked-file marking convention, and the failure mode when the pull conflicts with unpushed work (fails, preserves work, explains resolution) — directly consistent with readOnly.

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 before the routing advice, and nearly every sentence carries information (grouping, alternatives, params, return shape, failure mode). It is dense and the extension/untracked clause reads run-on, costing a point, but nothing is padding.

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

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

With no output schema, the description still describes the return shape (file count, likely main document, then paths per kind), the disk/network side effects, and the conflict failure path. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: extension matching is case-insensitive on path suffixes and also applies to untracked entries, and includeUntracked files are flagged '(untracked)'. The phrase 'filters untracked files as well' is slightly ambiguous about how extension interacts with untracked entries.

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 file in the project'), plus the grouping scheme (LaTeX sources, bibliographies, figures, other) and the precondition that it pulls latest commits first. An agent can distinguish it from list_sections, project_summary, and search_project without opening a 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: use this to find exact paths before reading/editing, use project_summary when counts suffice, use search_project to find which file mentions something. This is textbook when-to-use and when-to-use-a-sibling 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?

Beyond the readOnlyHint=true / openWorldHint=false annotations, it discloses a non-obvious behavioral trait: it reads local configuration only, 'answers without contacting Overleaf and proves nothing about access.' That caveat prevents the agent from misreading a successful listing as evidence of connectivity or permissions, and the return format is described too.

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, then usage triggers, then the local-only caveat and return format. Four sentences, each carrying distinct information with no restatement of the name 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?

No output schema exists, and the description compensates by explaining the return format ('one line per registered name, marked (default)'). Combined with the annotations covering the safety profile, 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?

The tool takes zero parameters, so the baseline is 4. The description does add cross-tool context by noting the `project` argument on other tools accepts an Overleaf address for unlisted projects, but that is not a parameter of this tool itself.

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

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

Specific verb+resource: 'List the Overleaf projects this server is configured to reach, marking which one is the default.' It is clearly distinct from sibling tools like project_summary and project_status, which operate on a single project rather than enumerating registered ones.

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 triggers are given: 'when a request is ambiguous about which paper it means, or when another tool reports an unknown project.' It also covers the negative case — a project absent from the list is still reachable by passing its Overleaf address as `project` — so the agent knows the list is not exhaustive.

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=true and openWorldHint=true already covering safety, the description adds substantial behavior: it does not follow includes, skips commented-out headings, pulls from Overleaf first, and enumerates failure modes (missing, binary, out-of-project path). This goes well beyond the annotations.

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

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

Front-loads the purpose, then usage, then file-scoping constraints, then return format. Every sentence carries distinct information with no filler.

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

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

No output schema exists, and the description fully specifies the return shape (one indented line per heading as \section{Title} [lines start-end] or a 'none' message) plus failure behavior. 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 both parameters are already documented, setting a baseline of 3. The description still adds meaning by clarifying that path addresses exactly one file and that includes are not traversed, which shapes how the agent uses the parameter.

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 (List) and resource (sectioning commands in one .tex file) and pins the exact scope (\part down to \subparagraph, including starred forms). It is immediately distinguishable from siblings like read_file and project_summary.

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

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

Explicitly says to call it before read_section or edit_section and explains why (to get the exact titles they match and to address by title rather than shifting line numbers). It also states the constraint that path names a single file and \input/\include are not followed, so the agent knows when to call it again per 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 flag destructive=true and non-idempotent, and the description adds substantially beyond them: the move only touches the local clone, Overleaf is untouched until push_changes, a pull happens first, references are not rewritten, and the failure path is described (nothing moves, reply explains why).

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?

Purpose and the local-vs-remote distinction are front-loaded, and the subsequent sentences each carry distinct operational information (reference breakage, cross-project workaround, pull behavior, failure semantics). It is dense and runs long, but no sentence is 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?

No output schema exists, yet the description covers the return/behavior semantics an agent needs: the pull-first behavior, the local-only mutation, and what the reply reports on failure. Nothing required to invoke this mutation correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: both paths are relative to the same project's root and must stay inside the project, and fromPath must be an existing file. It does not restate the format examples already 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 pair (move or rename) on a precisely scoped resource (a file inside one project), and clarifies it also creates missing parent directories. An agent can distinguish it from write_file, delete_file and cross-project transfers 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 alternatives and preconditions: cross-project moves should use read_file plus write_file, and stale LaTeX references must be found with search_project and repaired with replace_text before pushing. It also names the step that follows (push_changes).

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?

Discloses behavior well beyond the readOnlyHint/openWorldHint annotations: the call performs a pull, that pull only updates the local clone, nothing changes on Overleaf, no local edit is dropped, a conflicting pull does not fail but adds a WARNING and leaves the clone unchanged, and first-time projects get an initial clone so the first report shows nothing pulled. These are exactly the non-obvious side effects an agent must know before calling.

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 purpose and the report contents, then layers usage, side effects, conflict handling, and return format with no filler sentences. Each clause carries distinct information an agent needs.

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 describes the return shape ('plain name: value lines'), and it covers the pull side effect, conflict outcome, and cold-start clone case. An agent has everything needed to call it correctly and interpret 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 description coverage is 100% and the single 'project' parameter already documents the accepted forms (Overleaf address, 24-character id, registered name, omit for default). The description adds no parameter-level detail, so the baseline 3 applies; the first-time-clone note is behavioral, not parameter semantics.

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

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

States a specific verb and resource ('Report where one project's local clone stands against Overleaf') and enumerates the exact contents of the report: branch and head commit, pulled commits, unmerged commits, unpushed local commits, uncommitted edits, and the last ten commits. It is clearly distinguishable from siblings and even names show_diff as the tool for reading pending edits themselves.

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 trigger ('Call it to learn whether there is anything to push or anything new from a collaborator') and routes the adjacent need to a named alternative ('use show_diff to read the pending edits themselves'). The only thing not spelled out is an outright when-not case, but the alternative tool covers the main ambiguity.

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 readOnly/openWorld safety; the description adds substantial behavioral context beyond them: mainFile is only a heuristic guess with the exact candidate list and a caution to verify \begin{document}; the Overleaf pull is attempted first and aborts on conflict with unpushed local work while preserving that work; the first call clones the project and is therefore slower.

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 contents, then usage routing, then caveats; every sentence carries distinct information. It is dense and slightly long for one paragraph, but there is no filler.

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

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

With an output schema present, return shape need not be re-explained, yet the description still covers the main applicable risks: the guess-based mainFile, clone-on-first-call latency, and the pull-conflict failure mode. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% so the parameter is already documented, but the description adds meaning the schema lacks: the project may be any project the default token reaches, registered or not, extending beyond the schema's 'registered project name' wording.

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 (summarize) and resource (one project), then enumerates the exact return contents (file counts by kind, likely main document and section count, pending local work) and the intent (orient at task start). It is immediately distinguishable from read-oriented siblings like list_files and project_status.

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: use list_files for every path, list_sections for a document's outline, project_status for commit-level sync state, and this tool to orient at the start of a task. When-to-use and when-to-use-something-else are both 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 only flag it as non-read-only, destructive, non-idempotent and open-world; the description adds substantial context beyond that: the server re-checks and rebases onto collaborator pushes, conflicting edits are refused with both versions reported and no work lost, and pending commits from an earlier refused push ride along. It also discloses that the effect is immediate and public and that only the chosen project is pushed.

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 prerequisites, then conflict behavior, then return values. Nearly every sentence carries load, though the multi-clause sentences make it denser than strictly necessary.

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 mutation tool with no output schema, the description covers the essentials: prerequisites (show_diff, compile_project), conflict/refusal semantics, what is preserved on failure, scoping, and the return value ('the new commit hash and the diff that was published, or reports that there was nothing to push'). Nothing an agent needs to invoke it safely 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 meaning beyond the schema: commitMessage labels the single commit formed from pending edits, while commits already queued from an earlier refused push keep their own messages and go out with it. It also implies project scoping via 'Only the chosen project is pushed.'

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 ('Publish every pending local edit to Overleaf as one commit') and explicitly positions itself against siblings with 'the only tool that changes the project collaborators see.' An agent can distinguish it from sync_project, replace_text, and write_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?

Names prerequisites and ordering explicitly: 'Call show_diff first, and compile_project when the edit could break the build.' It also describes the conflict outcome that tells the agent when a push will be refused, giving both when-to-use and what-happens-next 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 only cover the safety profile (readOnlyHint, openWorldHint); the description adds substantial behavioral context beyond them — the pre-read commit pull, the 60,000-character plain-text cutoff, truncation-without-revision in revision modes, and the exact failure conditions (missing/binary file, out-of-project path, mode+line-range conflict, startLine after endLine).

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 is a dense single block, but front-loaded with the core action and ordered sensibly (modes, then edit workflow, then truncation, then failures). The delta-application recipe is arguably reference material rather than selection guidance, which slightly dilutes conciseness.

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 and a complex multi-mode tool, the description carries the full burden and does so: return format (plain text vs revision JSON), revision/hash semantics, truncation behavior, and all documented failure paths. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema omits: startLine alone reads to the end, endLine is clamped, and it documents the exact delta-application algorithm (split on newline, replace deleteLineCount lines at 1-based startLine, join). It stops short of documenting every parameter (e.g. project resolution), so not a full 5.

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 precise verb+resource ("Read one text file from the project") and adds the distinguishing behavior that it pulls the latest Overleaf commits first. It is clear what the tool does, but it never explicitly contrasts itself with the closely related sibling read_section, so the agent must infer the boundary from the resource wording.

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 explicit selection rules for each mode: "Use a line range to sample a large file, mode=full before an edit that passes expectedRevision, and mode=smart to re-read a file already read." Each variant is tied to a concrete situation, 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.

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

Annotations only give readOnlyHint/openWorldHint; the description adds substantial behavior: source resolution (Overleaf first), an explicit output cap of 60,000 characters with truncation, the boundary rule that stops before \appendix/bibliography/\end{document}, and the failure mode of returning existing titles. That is a lot of operational context beyond the annotations.

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

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

Front-loaded with the core action and free of filler, but it is dense: matching rules, truncation limit, source precedence and fallback behavior are packed into a few long multi-clause sentences, which would read better split out.

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 fully: it says what is returned (the section's stored LaTeX, truncated at 60,000 chars) and what happens on no match. Combined with the boundary and source rules, an agent has everything needed to call 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%, yet the description goes past it by explaining that sectionTitle is matched case-insensitively against the brace title (not the [short] title), with exact match winning and otherwise first-containing match in document order — plus the concrete consequence that a short fragment may resolve to an earlier section. This is real added meaning for a required parameter.

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

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

Opens with a precise verb+resource+scope: 'Read one section of a .tex file by its title', then defines the exact boundary (heading to next heading at same or shallower level). It explicitly contrasts itself with read_file, so an agent can separate it from sibling tools 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?

States the positive trigger ('when revising one part of a paper, so the rest stays out of context') and names the alternative to avoid ('Prefer it over read_file'). It also points to list_sections as the disambiguation step and records the 'Pulls from Overleaf first' source precedence.

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

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

Annotations only declare the safety profile (destructive, non-idempotent, open-world). The description goes well beyond: it explains that edits land only in the local clone until push_changes runs, that replaceWith is inserted literally with no $ substitution, that a failed match changes nothing and returns a count, and what the return value is. This is rich behavioral context an agent cannot get from structured fields.

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

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

Front-loads purpose and sibling preference, then failure modes, then the Overleaf/local/push lifecycle, then the return value. Dense but every sentence carries distinct information; 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 6-param destructive mutation with no output schema, the description covers the sync model, failure behavior, guard parameter intent, and return value. Nothing an agent needs to invoke it safely 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 already 100%, so the baseline is 3, but the description adds real meaning beyond it: the literal-insertion rule for replaceWith ($$, $&, $1 stay as written), the exactness/uniqueness constraint on findText, and the remedy of widening findText. These go past the schema's phrasing.

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 ('Replace an exact snippet of text in a project file') and immediately differentiates from siblings by naming write_file and edit_section. An agent can distinguish this from the other mutating tools 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 says to prefer it over write_file and edit_section for a targeted change, and states the when-not condition (snippet missing or occurring several times without replaceAll). It also names the follow-up tool (push_changes) needed to publish.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial context beyond that: the allowed file extensions, the fact that locally created files are invisible until push_changes, case-insensitivity, single-line matching, the 4,000-character line window, the 10-second regex timeout, and the Overleaf-first ordering.

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?

Information is front-loaded: purpose and return format come first, then the routing advice, then the constraints. It is dense and somewhat run-on, but nearly every clause carries a distinct constraint, so there is little 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?

For a search tool with no output schema, the description covers the return format, filtering limits, file-scope restrictions, error behavior and staleness caveats. An agent has everything needed to call it correctly and interpret 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 all four parameters are already documented, making 3 the baseline. The description does add a little meaning (maximumMatches counts matching lines taken in path order, and both modes are case-insensitive), but most of the extra detail is behavioral rather than parameter-specific.

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 (search) and resource (the project's text sources), specifies both modes (literal string or regex), and gives the exact return shape (path:line: text). It also distinguishes itself from read_file, read_section and list_files by naming when each is appropriate.

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 frames the use case ('when you do not know which file holds it') and routes the agent to the right siblings once the location is known ('use read_file or read_section, and use list_files to find a file by name'). Both the when and the alternative are stated.

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

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

Beyond readOnlyHint=true, it discloses non-obvious behavior: it does not pull first (comparison is against Overleaf as last fetched), it contacts Overleaf only to clone an unopened project, it covers only the chosen project, the diff is truncated at 60,000 characters, and it explains the 'No local changes pending.' output. This is exactly the context an agent cannot get from annotations.

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

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

Usage guidance is front-loaded and every sentence carries load-bearing information (scope, fetch semantics, truncation, empty-state message). It is dense and runs long, but there is little true filler.

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

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

With no output schema, the description still explains the return form (unified diff), the truncation limit, and the empty-result message, plus the fetch/scope caveats an agent needs to interpret results correctly. 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 description coverage is 100% and there is a single optional 'project' parameter already fully documented with address/id/name forms. The description adds no parameter-level 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?

States a specific verb (show) and resource (unified diff of the project's clone vs Overleaf), and enumerates exactly what the diff contains: uncommitted edits, new/deleted files, and commits from a refused push. This clearly separates it from siblings like project_status and push_changes.

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 conditions (before push_changes to preview what collaborators receive; after a refused push to inspect pending work) and names the alternative for a lighter need: 'use project_status when counts are enough.' Nothing is left to inference.

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

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

Goes well past the annotations: it discloses that nothing is sent upstream, that local edits are never discarded, that a dirty pull fails without attempting conflict resolution, that an unopened project is cloned instead and reports nothing pulled, and that the response contains pulled/unpushed commit counts. That is exactly the conflict-safety and side-effect detail the readOnlyHint/destructiveHint flags cannot 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 keeps every sentence load-bearing, but at six sentences it is denser than needed; the failure-mode and first-clone clauses could be tightened without losing information.

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

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

No output schema exists, and the description compensates by stating what is returned (pulled commit count and remaining unpushed commits). Combined with the sibling pointer and conflict behavior, an agent has everything needed to call this correctly on the first attempt.

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 behavior for the project argument that the schema does not: 'Only the chosen project is pulled; a project not opened before is cloned instead, and reports nothing pulled.' It maps the parameter to a distinct outcome rather than restating its format.

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 with directionality: 'Pull the latest commits from Overleaf into one project's local clone.' The direction is made unmistakable ('Nothing is sent to Overleaf'), which cleanly separates it from the sibling push_changes.

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 conditions ('call it to check explicitly that the clone is current, or after a collaborator says they have pushed') and when-not ('The read tools pull on their own, so this is rarely needed first'), plus a routing pointer to project_status for the broader picture.

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/openWorldHint/idempotentHint, but the description adds substantial non-obvious behavior: UTF-8 with no trailing newline added, exact-as-given content, path guards (absolute, .. escapes, .git refused), the Overleaf-pull-then-local-write ordering, and that the guarded overwrite is refused if the file changed or vanished. This is the kind of context an agent cannot get from the annotations.

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

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

A single dense paragraph, front-loaded with the operation and its two modes, then routing, then behavioral caveats. Every sentence carries information; nothing is padding or restated boilerplate.

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 stating the return value ('whether the file was created or overwritten'). Combined with the write semantics, path restrictions, and sync ordering, an agent has everything needed to call 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 description coverage is 100%, so the schema already documents all four parameters, and the description largely mirrors it for path and content. It does add meaning beyond the schema for expectedRevision — tying it to the Overleaf pull and stating when to omit it — which is genuinely useful call-selection guidance.

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 (write a whole file) plus the two modes it covers: create with missing parents, or full overwrite. It explicitly names the sibling operations to prefer for existing files (replace_text, edit_section), so an agent can distinguish it 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 explicit when-to-use ('add a new file') and when-not ('for an existing one prefer replace_text or edit_section, which cannot drop text you did not mean to rewrite'), plus the condition for including expectedRevision ('leave it out when creating a file') and a follow-up routing hint to push_changes.

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