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

Annotations already declare destructive/not-idempotent, so the description's added value is the all-or-nothing atomicity contract: 'All edits resolve before anything is written,' stale_anchor/ambiguous_anchor/version_conflict write nothing, and the error names the offending entry. It further discloses the no-op edge case (commit:null, unchanged:true, nothing pending), which no annotation covers.

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

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

Front-loaded with the action and the sibling routing in the first and eighth clauses, with error semantics clustered after. It is dense and slightly run-on (errors, no-op result, and message style all in one paragraph), but essentially every 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, multi-file write with no output schema, the description covers atomicity, per-error recovery, and what the return value contains (commit, head, and the unchanged no-op case). Nothing an agent needs to invoke it safely and interpret the result is missing.

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

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

Schema coverage is 75%, so the baseline is 3; the description adds real meaning on top — the content-vs-edits mutual exclusion per entry ('full content (new files) or quote-anchored edits… same rules as edit_file') and the intent/imperative convention for message ('Add related-work section'). It stops short of discussing base_version/branch, which remain schema-only.

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 ('Apply one multi-file change as ONE named commit') and immediately distinguishes scope from the closest sibling: 'use edit_file for a single file.' An agent can tell batch_write from edit_file/write_file/commit 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 selection rule: 'Use it for a coherent change across files; use edit_file for a single file.' It also gives the recovery procedure per error class (fix the entry and resend the whole batch; re-read and resend on version_conflict), which is when-to-use guidance in practical form.

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

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

Adds substantial behavioral context beyond the annotations: only the caller's own paths are committed, a collaborator's unsaved typing is excluded and reaches history as their own autosave, and a {committed:false} result is a normal no-op that still reports the current head and latest commits. These details explain side effects and result interpretation in a way the annotations do not.

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

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

The description is front-loaded with the core action and then uses each subsequent sentence to convey a distinct operational nuance: path ownership, normal no-op results, batch_write alternative, and message semantics. Despite its density, no sentence is redundant.

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

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

Given three parameters with full schema descriptions, annotations covering safety and idempotency, and no output schema, the description is complete enough to use correctly. It explains the unusual no-op outcome, return information such as head and latest commits, and the key behavioral boundary around collaborator paths.

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 meaning for the required message parameter by explaining that it titles the commit and replaces per-file titles from prior writes. Branch and project semantics remain mostly in the schema, so this is a modest enhancement rather than full parameter coverage.

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

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

States a specific verb and resource: commit files written on this branch that are not yet committed, under a message and author Claude. It clearly scopes the operation to the caller's own paths and distinguishes itself from batch_write for multi-file changes being made right now.

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 when the user asks for a named checkpoint, explains that every write already commits so {committed:false} is normal rather than a failure, and points to batch_write as the alternative for a current multi-file change. This leaves little ambiguity about when and when not to use the tool.

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

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

Annotations already establish that this is a non-read-only, idempotent, non-destructive operation. The description adds substantial behavioral context beyond annotations: parsed error structure, first-50 cap with totals, omitted box warnings, failure-log size, PDF completeness caveats, signed URL lifetime, pdfStale semantics, and job duration with progress notifications. It does not contradict any annotation.

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

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

The description is dense but front-loaded, opening with the core operation before output and failure details. Nearly all content is useful for a complex compile tool with no output schema, though the long paragraph and nested parentheticals could be more scannable. It is not padded, but the structure is heavy.

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?

Because no output schema exists, the description carries the full burden of explaining return values and does so thoroughly: error rows, total counts, log excerpt, pages, deep link, PDF URL and staleness behavior. It also covers timing, progress, error recovery, and user-actionable failure modes, leaving little an agent needs unstated.

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

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

With schema description coverage at 100%, the schema already documents the branch and project parameters in detail. The description mentions project context but does not add branch/project semantics beyond what the schema provides. Baseline 3 is appropriate because the schema carries parameter meaning.

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

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

The description begins with a specific verb and resource: "Typeset the project with latexmk." It also distinguishes itself from sibling get_pdf_url by explaining that get_pdf_url should be used for a fresh link instead of recompiling. An agent can identify the operation and immediate purpose 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?

It gives explicit when-to-use guidance (after coherent edits, not after each edit or just to check syntax) and when-not-to-use guidance. It also specifies retry limits, narration requirements, escalation behavior, and alternatives such as get_pdf_url. A missing-main-document precondition and user-actionable errors are also clearly called out.

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

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

Goes well beyond the annotations: it discloses the auth requirement and the specific failure mode for project-scoped tokens, how to surface that failure to the user, and the returned contentVersion contract ('pass it as base_version to the first write') that prevents a downstream write error. That is exactly the kind of context annotations (readOnly=false, idempotent=false) 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?

Return values and the blank/template distinction are front-loaded, then auth caveats follow. It's a single dense, em-dash-heavy sentence that takes close reading, but every clause carries 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 supplies the return contract (id, contentVersion, seeded files) and the follow-on usage of contentVersion. Auth prerequisites and error handling round it out; nothing an agent needs to call and chain from this tool 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 the 'template' property already documents folders, venue kits, 'blank', and the omit-default in detail. The description's mention of 'blank or from a template' and 'files the template seeded' restates rather than extends that. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('Create a new project'), names both modes (blank or from a template), and enumerates what it returns (id, contentVersion, seeded files). This is clearly distinguishable from siblings like list_projects or trash_project 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 a concrete precondition (a token with access to all projects; a project-scoped token cannot create) and an escalation path (relay the refusal; the user can mint an unscoped token in Settings → Agent access). It doesn't contrast against any sibling tool, but for a create operation the usage context is otherwise fully 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 say destructive/not-idempotent; the description adds the traits that actually matter: nothing is applied on any error result (atomicity), edits merge with a human's live typing, every call is one commit authored as Claude, the default commit title when message is omitted, and that a no-op edit yields commit:null with unchanged:true. That is substantive context 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-loaded with the core rule and the write_file contrast before error handling, and every sentence carries operational content. The parenthetical-heavy, brace-notation style packs a lot into one block, which is dense but not padded.

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

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

With no output schema, the description still covers the return contract (commit and head, commit:null with unchanged:true), all three documented error shapes, and the retry policy. Nothing an agent needs to invoke this destructive tool 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 83%, so the baseline is 3, but the description adds real semantics beyond it: it explains that occurrence is what the ambiguous_anchor candidates carry (so no re-read is needed) and what happens when message is absent ("Edit <path>" title). It says less about project and branch beyond what the schema already documents, so it stops short of 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 and mechanism — replace exact quoted text inside an existing file — and immediately distinguishes it from the sibling write_file ("write_file would discard it"). An agent can pick between edit_file and write_file without opening either schema.

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

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

Explicitly declares itself the default mutation path and names the condition that makes it mandatory (a person has the file open) versus the alternative that would destroy their work. It further routes per error class: re-read and retry at most twice on stale_anchor, resend with occurrence on ambiguous_anchor, re-read once on version_conflict, and clarifies that parallel tools on different files are safe.

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 say readOnlyHint=true and openWorldHint=false; the description goes well beyond by disclosing the 15-minute expiry, the signed-link nature, the exact response shape, why pdfStale is always false, and the staleness caveat that the link excludes edits made since that typeset. That is precisely the staleness semantics an agent could otherwise get wrong.

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 trigger, then return shape, then caveats — good ordering with no filler. The 'pdfStale is always false here because the link is to that file, whichever typeset wrote it (by you or by a person)' clause is dense and slightly convoluted, keeping it short of a 5.

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 enumerates the returned fields {pdfUrl, pdfFile, pages, typesetAt, deepLink} and explains the staleness semantics, plus the prerequisites (compile first). 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 `branch` and `project` are already fully documented in the schema, including the echo of {branch, head}. The description only refers to 'the PDF on disk for the branch' and adds no syntax or defaulting detail beyond that schema text, so the baseline 3 applies.

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

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

States a specific verb and resource ('a fresh signed link to the PDF on disk for the branch, without recompiling') and immediately contrasts it with recompiling, separating it from the `compile` sibling. An agent can tell exactly what this returns.

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 trigger conditions ('when a compile result's pdfUrl has expired (15 minutes) or the user asks to see the PDF again') and explicit exclusions with the alternative named ('if you have written on this branch since your last compile result, call compile instead'). It even handles the no-output case: 'No output yet → compile first.'

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds genuinely useful context: the shape of each returned record and the workflow rule against fabricating keys. It does not discuss cost, ordering, or behavior on empty .bib files, which keeps it from a 5.

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

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

Three short sentences: return shape first, then the mandatory-call rule, then the missing-key remedy. No filler, and nothing important is buried.

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 by spelling out the record fields an agent will receive. Combined with rich parameter documentation, an agent has enough to call it correctly; only edge cases such as an empty or missing .bib file go 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 both `branch` and `project` are fully documented in the schema, including the branch/head echo behavior. The description adds nothing about either parameter beyond the incidental phrase 'the project's .bib files', so baseline 3 applies.

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

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

States the resource precisely (citation keys defined in the project's .bib files) and even lists the returned fields, which lets an agent distinguish it from siblings like references_add or read_file. The verb is only implicit via the tool name rather than stated in the description, so it falls just short of a 5.

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

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

Explicitly instructs when to call ('Always call it before writing a \cite') and states a prohibition ('never invent a key'), then names the alternative path for missing keys: references_add or ask the user. That is exactly the when/when-not/alternative triad.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds value beyond that by disclosing the return shape ({label, file}) and a policy constraint (never invent a label). It does not mention pagination or the {branch, head} echo, though that is documented in the schema's branch parameter.

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

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

Two short sentences, zero filler. The return shape and the pre-write trigger are both front-loaded, and 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?

With no output schema, the description usefully states the result shape, and the branch/project semantics live in a fully documented schema. Only minor gaps remain (ordering, handling of duplicate or commented-out labels), which an agent can discover from the call itself.

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

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

Schema description coverage is 100%, and both the branch default/'main' behavior and the project scoping are fully explained in the schema itself. The description adds nothing about either parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('List \label targets defined in the project's .tex files') and even sketches the return shape '[{label, file}]'. No sibling tool (read_file, references_add, list_citations) does this, and the description alone lets an agent distinguish it 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 a concrete precondition — 'Call it before writing \ref, \eqref, or \cref — never invent a label' — which is a real when-to-use rule plus a prohibition. It does not name an alternative tool or an explicit when-not case, 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 cover readOnlyHint=true and openWorldHint=false, so the safety profile is known; the description adds genuine context beyond that — results are filtered by token scope, and the agentCreated flag marks exactly the projects trash_project accepts. It does not mention ordering, result size, or what an empty result means, which keeps it off a 5.

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

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

Three sentences, front-loaded with what is returned, then the calling condition, then the token-scope implication. The nested parenthetical about agentCreated and trash_project is information-dense but makes the second sentence slightly run-on.

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

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

With no input parameters and no output schema, the description carries the return-shape burden itself and does so by listing the fields returned. Nothing critical is missing for a zero-argument list tool, though ordering or result-size behavior is left unstated.

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

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

The tool takes zero parameters, so the schema baseline is already 4 and the description does not need to explain inputs. It still adds cross-tool value by noting that a project-scoped token makes the project argument optional everywhere, which informs how the agent calls sibling tools.

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 LaTeX projects') plus the exact scope ('this token can reach') and enumerates the returned fields (id, name, branches, rootFile, engine, agentCreated). Naming create_project and trash_project in passing makes it distinguishable from those siblings without opening their schemas.

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

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

Explicitly says 'Call it when you do not know the project id', which is a clear triggering condition, and adds that a project-scoped token makes the project argument optional elsewhere. It stops short of naming a when-not or a specific alternative tool, so it is clear context rather than a full routing rule.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: that the check verifies authentication as well as reachability, and what a failure means diagnostically (instance not responding vs. connector needs reconnecting). It does not describe what a success response contains, but with no output schema that is a minor 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?

Two sentences with zero filler: the first defines the check, the second front-loads the failure branch and the required agent behavior. Every clause 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?

For a zero-param health-check with annotations covering safety and no output schema, the description is nearly complete — purpose, scope, and failure handling are all present. The only omission is the shape of a successful result, which an agent can infer but would benefit from seeing stated.

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 there is nothing for the description to disambiguate; baseline 4 applies. No parameter semantics are needed or missing.

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 ('Check that the Aldine connector is reachable and authenticated') and goes beyond a bare connectivity ping by naming the authentication dimension. It is clearly distinct from every sibling tool, which all operate on projects, files, or citations.

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 failure clause gives an explicit exclusion ('do not go on to other tools') plus the user-facing action to take, which is exactly the routing guidance an agent needs. It stops short of saying when to call it proactively (e.g., first call in a session), so it is strong but not fully explicit about the positive trigger.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds substantive context beyond that — the meaning of contentVersion and the precise stale-write rule (a write is refused only when its own file changed after that version). It does not mention size limits or truncation behavior for large trees, so it is not fully transparent.

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

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

Two sentences, zero filler, with the core resource (file tree) front-loaded and the actionable version-handoff detail immediately after. The parenthetical about write refusal is dense but directly load-bearing.

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 return values — it names the key fields (rootFile, engine, contentVersion) and the {branch, head} echo is covered by the schema. It never sketches the tree's shape or ordering, which would help an agent parse a large result, so it is strong but not 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% and both parameters (branch, project) are documented there in detail, including defaults and token-scoping behavior. The description adds no parameter-specific syntax or defaults of its own, so the baseline 3 is appropriate; its value is concentrated on output semantics rather than inputs.

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 — the file tree of a project branch — and immediately names the additional payload fields (rootFile, engine, contentVersion). This distinguishes it from siblings like list_projects (which lists projects) and read_file (which reads one file), so an agent can pick it 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 proactive guidance: "Call it before working in a project you have not read yet," and explains that contentVersion should be forwarded as base_version to edit_file, write_file, or batch_write. It does not explicitly name an alternative for the already-known-project case (e.g. going straight to read_file), so it stops just short of full when/when-not 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 only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond that: open documents are flushed first, reads cap at ~100 KB, to_line is clamped to the last line, the result echoes the window served, and files with binary bytes are refused based on content rather than extension.

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?

Dense but front-loaded: freshness/flush first, then size cap and windowing, then the edit dependency, then version fields, then binary refusal. Every sentence carries actionable 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?

With no output schema, the description explains the important return fields (contentVersion, fileVersion, the echoed window and branch/head context implied by the schema notes). It covers freshness, limits, pagination, failure mode for binaries, and the downstream edit_file dependency.

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

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

Schema coverage is 60% and from_line/to_line have no schema descriptions; the description compensates by defining them as 1-based, inclusive, and clamped in the echo. path, branch, and project semantics are already fully documented in the schema, so the description adds value only where the schema is thin.

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 ('Read a text file') and immediately defines the exact semantics it returns: the editor's current state with open documents flushed. It distinguishes itself from the write siblings by tying its output to edit_file quote matching.

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 conditions: window files larger than ~100 KB with from_line/to_line, and read before editing so edit_file quotes match verbatim. It does not name a read alternative (none exists among siblings), so the guidance is clear context without an explicit when-not-to-use.

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 give readOnly=false, idempotent=true, openWorld=true, destructive=false, and the description adds real context beyond them: missing .bib files and folders are created, duplicates are reported, and an undefined-citation warning appears when no .tex loads the .bib. It also surfaces external-service failure modes and rate/budget limits, which the annotations do not imply.

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

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

Front-loaded with the action and resource, then returns, then caveats, then anti-patterns — a sensible order. It is dense with parentheticals but nearly every clause carries operational information; only the restatement of the bibFile default is redundant with the schema.

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

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

With no output schema, the description carries the return-value burden and does so fully: {key, bibFile, duplicate, created} plus the `created:true` case and the undefined-citation note. For a mutating, network-dependent tool it covers success, side effects, and partial-failure behavior.

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. The description largely restates schema content (default references.bib beside the root file) but does add meaning for `query` by excluding titles, which is the real semantic constraint on that 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 chain — resolve a DOI/arXiv/OpenAlex identifier to a BibTeX entry and append it to a .bib file on a branch — and names the concrete artifact involved. No sibling tool does this (list_citations reads, this writes), so an agent can distinguish it immediately.

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

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

Explicitly bounds usage: titles are not lookups, so ask the user for a DOI/arXiv id; on lookup-budget exhaustion or upstream failure, tell the user rather than retry in a loop. These are concrete when/when-not rules plus a failure-handling policy that no schema field could convey.

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

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

The annotations already mark this as destructive and idempotent, but the description adds important behavioral details: the 30-day restore window, that Aldine itself does not permanently delete data, and that the provisioned GitLab repository is deleted while a restore provisions a new one. It also discloses ownership and agentCreated refusal conditions.

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

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

The description is front-loaded with the core action, followed by side effects, refusals, and usage guidance. Despite its density, every sentence carries decision-relevant information for an agent.

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 one-parameter mutation with no output schema, the description covers the key concerns an agent needs: restore behavior, external GitLab repository deletion, refusal conditions, and when to invoke versus avoid the tool. The annotations are consistent with the description.

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

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

Schema description coverage is 100%, and the schema already explains that 'project' is a required project id from list_projects or create_project with no scoped-token fallback. The description reinforces the lifecycle context but does not add syntax or format details 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?

The description gives a specific verb and resource: moving a project to the trash. It also distinguishes this from create_project and list_projects by naming the lifecycle stage and the source of the project id.

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 explicitly states when to use the tool ('scratch projects the user asked you to throw away') and when not to use it ('never on your own initiative'). It also names refusal cases and an alternative action: asking the user to delete person-created projects in Aldine.

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 readOnly/openWorld annotations, it discloses what is counted and excluded (commands, comments, included files), that results come from compilation, and the error contract for a project with no main document — exactly the failure mode an agent would otherwise misread as a zero count.

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 dense sentences, front-loaded with the counting definition, then the usage direction and the error caveat. No filler, and every clause 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?

With no output schema, the description voluntarily supplies the return field list and the failure semantics, and the parameters are fully covered by the schema. Nothing an agent needs to invoke or interpret this call 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 description coverage is 100%, so branch and project are already documented, including the {branch, head} echo behavior. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

Names a specific verb+resource (word count of the document) and pins the exact scope — root file plus \input/\include graph, commands and comments excluded — plus the return shape {rootFile, total, files}. No sibling competes for this job, and an agent can tell instantly what it computes.

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?

"Use it for length questions instead of estimating from source" gives an explicit use condition and rules out the obvious wrong approach. It also pre-empts the ambiguous case (no main document is an error, not 0). No named sibling alternative is needed since none exists, but the guidance is clear rather than 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuinely non-obvious behavior beyond that: the collaborator viewport side effect, folder auto-creation, the .tex main-document promotion (newRoot), author/commit semantics, and the no-op case returning commit:null with unchanged:true. It does not discuss permissions or rate limits, hence 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?

The action statement and the edit_file routing are front-loaded, and nearly every clause carries information an agent needs. It is a dense single block with several ideas chained together, which costs some readability, but there is little wasted text.

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 must explain results, and it does: version_conflict shape, newRoot, the returned commit and head, and the unchanged:true/commit:null no-op case. For a 6-parameter destructive write tool this is complete enough 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 coverage is high (83%), so the schema carries most parameter meaning and the baseline would be 3. The description nevertheless adds value the schema does not state: conflict scope ('only a change to this file conflicts, never one to another file'), the re-read-once retry protocol, and the default commit title 'Update <path>' when message is omitted.

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 plus scope: 'Create a new file, or replace a whole file.' It immediately distinguishes itself from the sibling edit_file, so an agent can tell the two apart without opening either schema.

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

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

States explicitly when to prefer the alternative ('For an existing file prefer edit_file') and gives the reason (collaborator viewport teleporting, dropped typing). It also gives a decision procedure for conflicts: re-read and re-write once, then ask.

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