LaTeX-Agent

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

With no annotations, the description carries the full burden and does so well: it discloses that the tip and dirty files are frozen into a backup ref first (recoverable), that the working tree is hard-reset to the default branch, that the editor reloads, and it enumerates failure discriminators. This is exactly the destructive-but-recoverable context an agent needs.

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 its effect, then mechanism, then failure modes, so an agent can stop reading early. It is dense and somewhat long, and details about reason= discriminators border on return-value territory covered by the output schema.

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

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

For a one-parameter mutation tool with an output schema handling return values, the description supplies the trigger, the mechanics, the recoverability guarantee, and failure semantics. An agent has everything required to call it correctly at the right moment.

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 0% for the single project_id parameter. The description implies the project scope ('the project's parked AI session') but adds no format, source, or constraint detail for the parameter itself. The name is self-evident, so the gap is minor but real.

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 ('Abandon the project's parked AI session') and explains the concrete outcome it produces ('so a git push becomes visible in the editor'). It distinguishes the operation from its sibling adopt_session by pinning down exactly what state it manipulates (a parked session/* HEAD).

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 this right after pushing to hand the HEAD back to the default branch.' It also frames failure conditions (no_active_session, head_kept) that clarify when the call is valid. It stops short of naming adopt_session as the contrasting alternative or stating when not to call it.

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 no annotations, the description carries the burden and does well: it implies a read-only self-scoped query, flags unique_code as a sensitive claim credential that must be shown to the user with a secrecy reminder, and explains that expiry/quota fields are conditional on anonymous identity. It omits failure behavior (e.g., what happens with an expired anonymous identity) and any rate-limit or quota-reset semantics.

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, front-loaded with what is returned and followed by when to call it. It is dense with field names, which is justified here, but the parenthetical about the claim credential is slightly nested and slows scanning.

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-parameter read tool with an output schema, this is nearly complete: identity-dependent field availability is disclosed and the credential-handling instruction is included. A small gap remains around what the caller sees when no identity exists or when the anonymous quota is exhausted.

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 correctly implies no arguments are needed and instead spends its words on the returned fields.

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 the caller's own account status') and enumerates exactly what the response contains: unique_code, subscription tier, and anonymous-only expiry/quota fields. The scope qualifier 'caller's own' separates it cleanly from project/paper/file siblings, which all operate on other resources.

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: 'after onboarding to report status' and 'whenever the user asks about their account/quota/expiry.' No competing sibling exists for account introspection, so the absence of a named alternative is acceptable, though there is no statement of when not to call it.

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?

No annotations exist, so the description carries the full burden and does so well: it discloses the conflict behavior (nothing changed, conflict file list returned), that failure modes leave the session active and retryable, and that failures surface as reason= discriminators (conflict / head_kept / head_mismatch). This is exactly the kind of state/side-effect detail an agent needs before mutating a session.

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 the alternative, then failure semantics. Every sentence earns its place, though the final parenthetical stacks three discriminators and two remediations into one dense clause.

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?

An output schema exists, so return-value enumeration is unnecessary; combined with the description's coverage of conflict handling, retryability, and discriminator reasons, an agent has everything needed to invoke and interpret the 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 0% and the description never mentions project_id, so it adds no meaning beyond the schema. With a single, self-evident identifier parameter this is a minor gap rather than a critical one, landing at the baseline rather than above or below it.

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

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

States a specific verb and resource ('Adopt the project's parked AI session') and immediately elaborates the concrete effect: merging the session branch into the default branch and handing HEAD over. It is clearly distinguishable from abandon_session, which is named explicitly.

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 selection rule: 'Use instead of abandon_session when the session's work should be kept,' plus a fallback path ('or fall back to abandon_session') when resolution fails. Both the when and the when-not are covered.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the operation is non-destructive ('cannot disturb the existing content') and implies the file must already exist, but says nothing about permissions, failure modes if the path is missing, or the returned result.

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

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

Two tight sentences, front-loaded with the core behavior, with zero wasted words and the key constraint stated up front.

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?

An output schema exists, so return values need not be explained. However, for a mutation tool with no annotations and 0% param coverage, the description leaves the less-obvious parameters and error/permission behavior unaddressed.

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

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

Schema coverage is 0% with 4 parameters, so the description would need to compensate and does not. It never explains path, project_id, or the optional description field beyond the implicit notion of 'content', leaving an agent to infer their meaning from the schema alone.

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 (add/append) and resource (existing file) with a precise scope: content goes to the end. It distinguishes itself from write_file/edit_file by contrast ('without restating what is already in it', 'needs no anchor text') rather than naming the siblings explicitly.

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 concrete when-to-use examples (bibliography entries, appending a section, extending a log) and implies the alternative by noting it needs no anchor text and won't disturb existing content. It stops short of naming edit_file/write_file as the alternatives an agent should choose between.

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 no annotations, the description carries full burden and does so: it discloses the exact state change (hidden from default listing, quota exempt), the reversibility guarantee, and the non-destructive side effect ('files, compile and review keep working, so nothing is destroyed'). This is exactly the behavioral context an agent needs before mutating state.

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 tight sentences, front-loaded with the core action and effect, then reversibility, then the usage guidance. No wasted words.

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 full surface for an archival mutation: what changes, what does not change, how to undo it, and when to invoke it. Although an output schema exists, the description doesn't need to describe return values, and the behavioral picture is complete.

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

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

Schema coverage is 0% and there is one required parameter (project_id). The description doesn't explain the format or source of project_id, but the parameter name is self-explanatory and only one param exists. Baseline 3 is appropriate for a single obvious identifier.

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

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

The description states a specific verb+resource ('Archive a project') and immediately defines the behavioral effect: hides from list_projects and stops quota counting. It is clearly distinguishable from siblings like unarchive_project and list_projects, which it explicitly names.

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 states when to use it ('empty/abandoned projects the user wants out of their list') and names the inverse tool ('Reversible via unarchive_project'). The agent knows both the target scenario and the reversal path.

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 no annotations, the description carries the full burden and does a good job: it discloses that the job is asynchronous and keeps running server-side, the recommended polling cadence, and termination semantics including the cancelled case. It does not cover failure modes on submission (e.g., missing project or invalid engine) or any limits, which keeps it short of a 5.

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

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

The polling instruction is helpfully front-loaded, but the final sentence repeats the async/job_id/poll-for-outcome point already made twice earlier. Two of three sentences carry distinct value; the third is redundant 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?

An output schema exists, so return values needn't be explained here, and the async control flow is fully documented. The only real hole is the semantics of the filename and project_id parameters for an agent that has only the schema's bare titles.

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 0%, so the description must compensate; it explains the engine enum well, including that 'auto' honors the entry file's '% !TeX program' magic comment. However, project_id and filename are never explained, and filename (which likely selects the entry file) is a meaningful gap.

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 (submit an asynchronous LaTeX compile job) plus the immediate return value (job_id). It is clearly distinguishable from the sibling compile_status, which it names as the follow-up step.

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 operating instructions: poll compile_status roughly every 5 seconds until succeeded/failed/cancelled, treat cancelled as the user having cancelled, and do not retry. This leaves no ambiguity about when to call this tool versus compile_status.

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 no annotations, the description carries the full burden, and it delivers: read-only intent, the 64KB tail cap, the exists=false fallback when no log exists, and the log's block format (! <error> / l.<line> <source>). It omits any permission/authorization notes, so it is strong but not exhaustive.

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

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

Three sentences, front-loaded with purpose, then the usage trigger, then the return behavior. Every sentence earns its place with no filler.

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

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

An output schema exists so return values need not be spelled out, yet the description still adds the tail cap and exists=false fallback. With one simple param, purpose, trigger, and behavior are all covered – 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 0%, so the description is the only source, yet it never explains project_id beyond implying 'the project's last compile'. The single obvious required string param is inferable from context, but the description adds little explicit semantic detail about it.

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

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

States a specific verb (read) and resource (raw engine log output.log of the project's last compile), and distinguishes itself from the structured-error path handled by siblings like compile_status. An agent can identify the tool 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 an explicit condition to use it ('after a failed compile when the structured errors lack a file/line') and implicitly the condition not to (when structured errors already carry file/line). It doesn't name the alternative tool (compile_status) directly, 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?

With no annotations, the description carries the full burden and does most of it: it discloses that the no-job mode is side-effect free (no compile submitted), enumerates terminal statuses (running/succeeded/failed/cancelled), explains cancellation provenance, and warns against treating a lagging last_success_seq as proof of compilation. The remaining gap is the non-terminal payload shape beyond the four states, which is partly covered by the output schema.

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

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

Front-loaded with the mode split and structured around it, so the agent hits the decision point first. It is dense and runs long, with a couple of clauses (engine, state_seq bookkeeping detail) that could be tightened, but essentially every sentence carries operational instruction rather than 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 single-parameter tool with an output schema, the description supplies everything an agent needs to invoke it correctly and interpret results: which mode to pick, which statuses are terminal, what cancelled means, and the is_fresh_green caveat that prevents a wrong conclusion. Nothing material is left to inference.

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 0% — job_id has no description at all — so the description must compensate, and it does: it defines the parameter's two states (absent vs present), its origin ('the asynchronous compile job returned by the compile tool'), and what each state changes in behavior and return value. That is more meaning than the schema could ever convey.

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 'Two modes' and then specifies exactly what each returns: WITHOUT job_id the latest compile state (explicitly noting no compile is submitted), WITH job_id the polled status of an async job. It names the sibling tools compile and compile_log, so an agent can place it in the workflow 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 ordering ('use this FIRST when you need to know whether the project compiles'), an explicit pairing ('pair it with compile_log for the raw error log'), and an explicit stop condition for the cancelled case ('do not keep polling or retry the compile'). It also bounds polling at roughly two minutes, which is a when-to-stop rule rather than generic advice.

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 no annotations, the description carries the full behavioral burden and does so well: it discloses one-time display ('shown exactly once — hand it to the user, do not store it') and rotation semantics ('Minting again rotates: the previous token is revoked'). These are exactly the mutation/reversibility and handling traits an agent cannot infer elsewhere.

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 tight sentences, front-loaded with the core action, then usage, then the critical one-time/rotation caveats. Every sentence earns its place with no redundancy.

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

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

An output schema exists, so return-value detail is unnecessary, and the description correctly highlights the token's one-time nature. The only gap is the absence of any authentication/permission prerequisite for minting, but otherwise the definition is complete for a single-parameter mutation.

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 0% for the single project_id parameter, so the schema adds no meaning. The description only implies project_id identifies 'one of your projects' and offers no format or acquisition guidance, so it partially compensates but leaves a gap.

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: 'Mint (or rotate) the HTTP git token for one of your projects', and clarifies the downstream purpose (clone/push/pull over HTTP). This clearly distinguishes it from siblings like sync_from_git and get_git_status, so an agent can tell them apart without opening 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?

'Use when the user wants to continue a project created or synced through this MCP client from their local machine' gives a clear triggering condition. It does not, however, name any alternative or exclusion (e.g., when to prefer sync_from_git instead), so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden, and it does add real behavioral context: the per-plan project quota applies and the create path is explicitly preferred over file-by-file writes for git-backed sources. It omits permission/auth requirements and what happens when the quota is exhausted.

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 returned project_id are front-loaded in the first sentence, with quota and git-routing context following. The third sentence is long and reads more like a user-facing instruction than tool documentation, but it still carries routing value.

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

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

An output schema exists and the description correctly points to project_id as the takeaway, so return explanation is not needed. Quota behavior is covered; failure modes (invalid template_id, quota exceeded) and auth prerequisites are the remaining gaps for a simple two-parameter create tool.

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

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

Schema coverage is 0%, so the description must compensate. It clarifies template_id as an 'official template's template_id' (implying a value sourced from list_templates), which adds meaning, but `name` is left entirely unexplained and no format/constraint detail is given for either.

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 personal project'), notes the optional template path, and explicitly names the sibling workflow (sync_from_git) it is distinct from. An agent can distinguish this from write_file/upload_file/sync_from_git 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?

Gives a concrete routing rule: if the source already lives in git, create the project here and pull with sync_from_git rather than writing files one by one. That names both the condition and the alternative. It stops short of guidance on when to pass template_id versus naming freely (e.g., consult list_templates).

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 no annotations, the description carries the full burden and does so: it discloses a destructive side effect ('discards any pending review change that has not been merged yet'), an auth constraint ('Read-only sessions cannot call this'), and the return value ('the new commit_sha'). This is exactly the behavioral context an agent needs for a mutation 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-loaded with the core action, followed by usage guidance, return value, side effect, and auth note. Four dense sentences, each carrying distinct information with no redundancy.

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

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

For a mutation tool with no annotations and 0% schema coverage, the description covers purpose, timing, side effects, auth, and return value. An output schema exists, yet the description still names commit_sha, and nothing needed to invoke 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 0%, so the description must compensate. It explains 'title' (short human-readable title) and 'body' (optional longer body describing what this version captures), clarifying meaning and optionality. 'project_id' is left implicit, but its role is evident from the 'project's working tree' framing.

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: 'Snapshot the project's current working tree as a named git version', with the parenthetical identifying it as the platform's version history. An agent can distinguish it from siblings like list_versions and get_git_status without opening any schema.

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

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

Gives clear when-to-use guidance ('Call this BEFORE large or risky rewrites so the change can be rolled back or reviewed later') and a when-not condition ('Read-only sessions cannot call this'). It stops short of naming a sibling alternative, but the triggering context is explicit.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses the non-destructive scoping guarantee and the hard pre-condition that old_string 'must appear exactly once' and be copied verbatim from read_file. It stops short of describing failure behavior (what error occurs on non-unique match) or permission requirements, 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 dense sentences, workload front-loaded with the core behavior before routing advice and the critical constraint. 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?

An output schema exists, so return-value explanation is unnecessary, and the description covers the scoping and uniqueness semantics an agent needs to call it correctly. Missing only edge-case behavior (non-unique match handling, permissions), a minor gap for a well-scoped edit tool.

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

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

Schema coverage is 0%, so the description must compensate. It richly documents old_string (uniqueness, verbatim copy, indentation) and implies new_string, but leaves path, project_id, and description undocumented. It covers the highest-risk parameters but not the full 5-param surface.

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 precise verb ('Replace one exact snippet') and resource ('inside an existing file') with an explicit scope guarantee ('leaving the rest byte-for-byte untouched'). An agent can immediately distinguish it from write_file and append_to_file 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 names the alternative and the condition that selects it: 'Prefer this over write_file for any change to a file that already exists.' This is a direct when-to-use/which-sibling routing instruction.

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 no annotations, the description carries the full burden and does well: it discloses that read_file cannot decode the binary zip format, that failure surfaces as isError with an honest note, and warns against inventing content. It omits permission or size/pagination constraints, but the failure mode and the anti-hallucination rule are the important behavioral facts.

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 the purpose and output shape, followed by the sibling comparison and the failure contract. Every sentence earns its place with no repetition of structured fields.

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?

An output schema exists, so return values need not be spelled out, and the description already covers the error path. The remaining gap is the undocumented required parameters, which leaves the agent guessing at how to construct the call.

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 0%, so the description must explain that project_id identifies the project and path is the docx location within it; it says nothing about either. 'Path' is partially inferable from the tool's domain, but project_id is entirely undefined in both schema and description.

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 the TEXT CONTENT of a Word document (.docx)') and scopes the output to headings, paragraphs, tables and lists in document order. It explicitly distinguishes itself from read_file, so an agent can select 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?

Names the alternative (read_file) and the condition that should route to this tool ('when the user asks you to convert or reference a Word document'), plus the reason read_file fails. It does not address the other plausible sibling, render_docx_preview, leaving some ambiguity on when to preview versus extract.

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?

No annotations are provided, so the description carries the full burden. It discloses the returned payload shape (anchor, replies, authors), which is useful, but says nothing about read-only safety, permissions, or behavior when comment_id does not exist.

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

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

A single tight sentence with no filler, front-loading the resource and the thread contents. Every word 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 simple one-parameter read tool with an output schema already covering the return shape, the essentials are mostly present. It falls short on parameter guidance and on routing relative to list_comments and reply_comment.

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 0% and the description never mentions comment_id -- no format, type, or source hint (numeric ID, UUID, or where to obtain it). With one required undocumented parameter, the description fails to compensate for the schema gap.

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

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

The description names the resource and scope precisely: a single review comment plus its reply thread, including the anchor and reply authors. This implicitly contrasts with list_comments (many) and reply_comment/resolve_comment (mutations), though it never names those siblings explicitly.

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

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

Usage is only implied by what the tool returns -- fetch this when you need one comment's full thread. There is no explicit when-to-use, no condition for choosing it over list_comments, and no note about what to do if the comment has no replies.

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?

No annotations, so the description carries the burden, and it clearly signals a read-only inspection ('Read this project's git state'). It discloses the scope of returned data and its role as a pre-flight check, though it says nothing about permissions or behavior when the project has no repo/remote configured.

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 what the tool reads, then the when-to-use guidance, in two dense sentences. The parenthetical REST path earns its place by giving the alternative configuration route.

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 read-only single-param tool with an output schema, the definition covers purpose, contents, and usage routing fully. Nothing needed to call it correctly is missing, and return values are documented in the output schema.

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

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

Schema coverage is 0% for the single required project_id param, but the description's repeated 'this project' framing gives implicit meaning to that argument. It adds little beyond the self-evident identifier, so it neither compensates nor misleads.

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

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

States a specific verb (read) and resource (this project's git state), then enumerates the exact fields returned: remote URL, branch, HEAD sha, ahead/behind counts, uncommitted changes, oversized files. This lets an agent distinguish it from sync_from_git without opening either schema.

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

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

Explicitly says 'Read this before sync_from_git to decide whether a pull is needed or the remote still has to be configured', naming the alternative tool and the decision it informs. It even supplies the fallback configuration path when no remote is set.

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?

No annotations are provided, so the description carries the full burden. It discloses the shape of returned comment data (anchor type, author, severity, resolved state, content) and the pdf/synctex relationship, but says nothing about permissions, pagination, or result volume for a list operation.

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, front-loaded with the list action and scope, with the filter and cross-tool hint following. The parenthetical field enumeration is dense but earns its place by describing result shape; the sentence is 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?

An output schema exists so return values need not be spelled out, yet the description supplements with anchor-field context; it covers the filter parameter and the synctex workflow link. Given only two simple parameters, the remaining gap (pagination/permissions) is minor.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: 'resolved' is described as a filter and 'round_id' is implicitly scoped to the review round being listed. Both parameters gain meaning, though no format details for round_id are given.

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 (a review round's comments) and enumerates the anchor fields returned. It is clearly distinguishable from siblings like get_comment_thread, resolve_comment, and reply_comment, which handle threads or mutations rather than enumeration.

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 usage cue ('Filter by resolved') and a downstream workflow pairing with synctex_backward for pdf_region anchors. It does not explicitly contrast with get_comment_thread (single-thread detail), so the exclusion guidance is incomplete.

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 no annotations, the description carries the full behavioral burden. It notes the output is a JSON tree but says nothing about recursion depth, hidden/ignored file handling, permission requirements, or pagination, which matter for a file-listing 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?

A single front-loaded sentence with the verb first and the return format trailing. No wasted words, though the extreme terseness leaves the behavioral gaps noted elsewhere.

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?

An output schema exists, so return values need not be explained, and there is only one obvious parameter. However, the description omits behavioral context (recursion, filtering, permissions) that an agent would want when choosing among the many list_* and file-access siblings.

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?

One parameter (project_id) at 0% schema description coverage, so the description must compensate. It implies project scoping, but adds no meaning beyond the self-evident parameter name; baseline 3 is appropriate given the single, obvious 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), resource (project file structure), and output shape (JSON tree), which is enough for an agent to know what it returns. It is not explicitly differentiated from siblings like list_versions or list_projects, but the scope is clear.

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?

No guidance on when to use this versus read_file, list_versions, or list_projects, and no exclusions or prerequisites. The agent must infer usage from the name alone.

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 no annotations, the description carries the full behavioral burden. It usefully discloses the return cap ('up to 50') and the field set, but never explains pagination or what happens when a library exceeds 50 papers, which is the key behavioral question for this 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?

Two tight sentences, front-loaded with what is listed and what comes back, followed by the chaining hint. 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?

An output schema exists, so the description correctly does not re-document return values; it only adds the scope and cap. The missing piece is truncation/pagination behavior for libraries larger than 50 items.

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; the baseline of 4 applies.

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

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

States a specific verb and resource ('List the user's own paper library') and narrows scope with 'own', plus enumerates the metadata returned (id/title/status/folder/tags). It stops short of explicitly contrasting with the sibling search_papers, so an agent must infer the list-vs-search distinction.

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 usage context by naming the downstream step: 'Use the returned id with read_paper to extract text by page.' It does not state when to prefer search_papers over this tool, but the purpose context is unambiguous.

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

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

With no annotations, the description carries the full burden and does so well: a hard cap of 50 entries, most-recent-first ordering, inclusion of shared/team projects with owner_type/team_id and the caller's role, exclusion of file contents, and the default hiding of archived projects with the archived_at field added only when include_archived=true. These are exactly the non-obvious traits an agent needs 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-loaded with the core operation and scope, then behavior and routing. Sentences earn their place, though the trailing issue references '(#5507)' and '(#5773)' are internal tracking noise that adds no value 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?

An output schema exists, so return values need not be spelled out, yet the description still names the key fields and ordering. Combined with cap, inclusion rules, archive behavior, and the follow-on git tool routing, nothing needed 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 0% for the single parameter, so the description must compensate and does: include_archived defaults to hiding archived projects, and setting it true both surfaces them and adds an archived_at field per entry. That is meaning well beyond the bare boolean in the schema.

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

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

States a specific verb and resource plus the exact scope ('projects the user can open') and the metadata returned (id/name/updated_at/category/main_file). It is clearly distinguishable from siblings like list_files, list_papers, or list_versions 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 use it to resolve a project name to its id before calling project-scoped tools, and routes git-repository work onward to get_git_status / sync_from_git. It gives clear positive conditions but never states when not to use it (e.g., archive_project or create_project for lifecycle 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the access-control model (owner and members only), which an annotation-free schema would not convey, but says nothing about ordering, pagination, or what happens for a non-member caller; a read-only list tool needs less, but the coverage is partial.

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

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

One compact sentence with the resource named first, the return fields in a compact parenthetical, and the access/workflow note last. Every clause earns its place and nothing is padded.

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

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

For a low-complexity, single-parameter list tool with an output schema present, the description covers purpose, access conditions, and the follow-up call, which is everything an agent needs. Return-value detail is already handled by the output schema, so the inline field list is extra rather than 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 0% for the single project_id parameter, so the description is the only source of param meaning. It implicitly scopes the call to "a project" but adds no format or identifier detail, so the schema-plus-description pair leaves the parameter only self-evidently interpretable.

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 ("List a project's review rounds") and enumerates the returned fields (id/round_number/status/created_at), so the agent knows exactly what comes back. It does not explicitly contrast with siblings like list_comments, only points to it as a follow-up, so it falls short of full sibling differentiation.

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 real precondition ("Visible to the project owner and project members") plus an explicit next step ("use list_comments with a round id"), which tells the agent how this tool fits into a workflow. It stops short of saying when this tool is preferable to an alternative retrieval path, so it is clear context rather than full when/when-not guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose useful traits: the 100-item cap, newest-first ordering, and the returned fields. However it says nothing about pagination beyond the cap, how search matching works (substring/case), or behavior when nothing matches.

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, both front-loaded: the first gives the resource, returned fields, and ordering constraints; the second gives the motivating use case. No filler, no repetition of the tool name.

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?

An output schema exists, so return-value documentation is not required, yet the description still summarizes returned fields helpfully. For a read-only listing tool with no required parameters, the main remaining gap is pagination/matching behavior at the 100-item boundary, which is minor.

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

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

Schema description coverage is 0% for all three parameters (limit, search, category), so the schema supplies no semantics. The description partially compensates: 'resolve a template name like IEEE' implies the search parameter's purpose and the listed output includes category. But limit is never explained, and its relationship to the stated 'up to 100' cap is ambiguous.

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 official LaTeX templates), enumerates the returned fields (id/name/category/publisher), and gives scope constraints (up to 100, newest first). This clearly separates it from sibling list_* tools such as list_papers, list_projects, and list_versions, which cover different resources.

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 states the intended use case: resolving a template name like 'IEEE' into a template_id needed by create_project. That is a concrete when-to-use with a named downstream tool. It stops short of naming exclusions (e.g., when to use search_papers or list_files instead) but the intent boundary is clear.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'List' implies a read operation, but the description does not mention permissions, ordering, pagination behavior, or the effect of limit/since, leaving significant behavioral gaps.

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

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

The description is a single front-loaded sentence with no filler words. It is appropriately terse for a simple list tool, though the sparseness leaves the reader with no additional context.

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?

An output schema exists, so return structure need not be described. However, with no annotations and zero schema description coverage, the description should compensate for the undocumented parameters and behavioral expectations; it does not.

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 0%, and the description does not mention any of the three parameters. project_id is required, and limit/since control the result set, but none of their meanings or formats are explained anywhere.

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 ('commit history for the project'), so the agent knows this returns version/history data. It does not differentiate from nearby siblings such as create_version or get_git_status, leaving the boundary to be inferred.

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

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

The description gives no when-to-use guidance, no alternatives, and no prerequisites. It does not say whether this should be used instead of get_git_status or how it relates to create_version.

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 no annotations, the description carries the full behavioral burden and delivers almost nothing: it does not say what happens on a missing path, whether content is truncated, how binary or large files are handled, or what permissions are needed. Only the basic read semantics are conveyed.

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 short sentence with no filler and the core action front-loaded. It is efficient, though arguably under-specified rather than deliberately concise.

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?

An output schema exists, so return values need not be described. However, for a two-required-parameter file-access tool with zero annotation coverage and 0% schema coverage, the definition omits path resolution, error behavior, and any constraints — not complete enough to call it reliably.

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 0% and both parameters are required, yet the description says nothing about 'path' (relative to project root? absolute?) or 'project_id' format. This leaves both parameters undocumented in every available channel.

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 (Read) and resource (content of a project file), which is enough to distinguish it from write_file/edit_file/append_to_file. It does not explicitly contrast with read_paper, but the 'project file' scope implicitly separates them.

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

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

There is no guidance on when to use this tool versus siblings such as read_paper or list_files, and no stated preconditions (e.g., whether the file must exist or be text). The agent must infer usage entirely from the name.

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 no annotations, the description carries the full burden and delivers: it discloses output format (text extracted, page-numbered as [Page N]), a critical truncation behavior for long papers, and the recovery path (re-call with start_page/end_page). This is exactly the behavioral context an agent needs and cannot get from the schema.

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

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

Front-loaded with the core action, then usage, then discovery guidance, then the truncation caveat. Four sentences, each carrying distinct information with no redundancy.

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

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

An output schema exists, so return-structure explanation is unnecessary. Given that, the description covers the essentials: scope, discovery prerequisite, truncation, and continuation. 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 0%, so the description must compensate; it explains the purpose of start_page/end_page (continuing a truncated read) and contextualizes paper_id via the search-first guidance. It stops short of describing units, ranges, or defaults for the page params, leaving some gaps.

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

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

States a specific verb (Read) and resource (full text of a paper in the user's own paper library / uploaded PDFs), and clearly distinguishes this from the discovery siblings (search_papers, list_papers) by naming paper_id as the input it needs.

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 when-to-use ('answer questions about a specific paper the user uploaded') and a named alternative with its triggering condition ('Call search_my_papers first when you only know a topic/title, not the paper id'). Nothing is left to inference about routing.

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?

Since no annotations are provided, the description must carry the full behavioral burden. It specifies the output structure (PNG images written under /.docx-preview/), identifies the required external service (`render-worker`), and defines the fallback mechanism if that service fails.

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 densely packed with necessary information, but the first sentence is long. However, the logic flows clearly: Goal > Deliverables > Workflow > Contingency, making it very effective.

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 the lack of annotations and the complexity (rendering, external worker dependency, specific file paths for output, and fallback logic), this definition is exceptionally complete. It covers operational requirements and specific failure modes.

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?

While the description provides rich context for the resource being acted upon (a Word document in the project), it adds no specific semantic meaning to the input keys (`path`, `project_id`) beyond what a basic string schema provides. It falls into the minimum viable category when structural coverage is assumed.

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 explicitly states the action: 'Render a Word document... to per-page PNG images.' Crucially, it distinguishes this from `extract_docx_text` by framing the goal as analyzing visual layout rather than extracting content.

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

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

It not only states the primary use (studying visual layout) but also provides explicit instructions on workflow, advising the agent to 'Pair with extract_docx_text for the actual content.' It also dictates operational rules regarding service availability.

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 no annotations, the description carries the full burden, and it does disclose two real traits: the permission model (any active collaborator may reply) and an input validation rule (empty text is rejected). However, it says nothing about side effects, whether the reply notifies other users, threading/reply-depth behavior, or error conditions for a bad comment_id.

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

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

One front-loaded sentence plus a short parenthetical, with no filler or redundancy. The validation note is tucked into a trailing parenthetical rather than given its own clause, but overall it is tight and appropriately sized.

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?

An output schema exists, so return-value explanation is not required, and the tool is simple with only two required parameters. Still, the source/format of comment_id and the result of the reply are unspecified, which leaves modest gaps for a mutation tool with no annotations.

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

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

Schema description coverage is 0%, so neither parameter is documented in the schema. The description only adds meaning for 'text' by noting empty values are rejected; 'comment_id' is left completely unexplained — no format, source, or how to obtain it. With low coverage the description should compensate more than it does.

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

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

The description states a specific verb and resource — 'Reply to a review comment' — which clearly separates it from siblings like resolve_comment, list_comments, and get_comment_thread. The parenthetical ('any active collaborator of the project') further scopes the action by permitted actor, though it never names the sibling tools it is distinguished from.

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

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

Usage is implied: reply when you want to respond within a comment thread, as opposed to resolving (resolve_comment) or reading (get_comment_thread/list_comments). No explicit when-to-use, when-not-to-use, or alternative is given, so an agent must infer the routing from sibling names alone.

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 no annotations, the description carries the full burden and does disclose two real facts: the operation is bidirectional (toggle) and only the round's student may perform it, including a ticket reference. It does not say what happens on unauthorized attempts, whether the toggle is idempotent, or how errors surface.

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 with the purpose front-loaded and the permission constraint second — appropriately sized. The '#4818 FR2' tracker reference is minor internal noise that adds nothing for the calling 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?

An output schema exists so return values need not be explained, and the auth constraint is covered. However, for a 2-parameter tool with zero schema description coverage and no annotations, the description leaves the parameter layer entirely 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 0%, so the description must explain both parameters and largely does not. The parenthetical '(or un-resolve)' hints that a boolean exists but never maps to 'resolved', never mentions its default of true, and says nothing about 'comment_id'.

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 ('Resolve (or un-resolve)') and resource ('a review comment'), making the state-toggle distinct from reply_comment and get_comment_thread. It does not explicitly name those siblings, so it stops 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?

The 'resolve (or un-resolve)' phrasing implies when the tool applies, but no alternatives are named — an agent gets no explicit routing between this, reply_comment, and send_feedback. The only stated constraint is authorization, not use-case selection.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions differing backend coverage but omits whether the call is read-only, pagination/limit behavior, project scoping requirements, rate limits, or the cost of switching sources. The '(#3596)' ticket reference adds no behavioral value.

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

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

Two short sentences, front-loaded with the core action and the backend choice. The trailing '(#3596)' issue reference is pure noise and should be removed.

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?

An output schema exists, so return values need no explanation. But with zero schema description coverage across four parameters and no differentiation from the paper-related siblings, the definition leaves an agent unable to call this correctly without inspecting the schema and guessing at the sibling boundary.

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 0%, so the description must compensate for four undocumented parameters. It clarifies only 'source' (enum values plus the OpenAlex default); 'query', 'limit', and the required 'project_id' are left completely unexplained.

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

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

The description states a specific verb and resource ('Search academic papers') and names the two backends it queries. It does not distinguish itself from the sibling 'list_papers' or 'read_paper', so an agent must infer the boundary between searching and listing.

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

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

It gives a conditional usage hint for one parameter value ('Use source="semantic_scholar" for broader AI/CS preprint coverage and citation-influence metrics'), which implies when to prefer that backend. However, it says nothing about when to use search_papers vs siblings like list_papers, nor about any prerequisite conditions.

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?

No annotations are provided, so the description carries the full burden. It discloses one meaningful behavioral requirement — pass the message verbatim and do not summarize — but says nothing about what happens to the feedback, whether it is anonymous, or any auth/rate constraints. Adequate but incomplete for a zero-annotation 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?

Two sentences, front-loaded with the action and then the usage condition plus the verbatim instruction. Every clause earns its place with no filler.

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

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

An output schema exists, so return values need no explanation, and the description covers the when and the how adequately. The only gap is the undocumented 'context_hint' parameter, which is minor given it is optional with a null default.

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 0%, so the description must compensate. It clarifies the 'message' parameter ('pass the user's message verbatim'), but says nothing about 'category' beyond the self-evident enum values and omits 'context_hint' entirely, leaving one of three parameters undocumented.

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 ('Submit feedback about the product') with an explicit source constraint ('from the user's own words'). It is trivially distinguishable from every sibling, none of which concern feedback submission.

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 enumerates the trigger conditions: 'when the user expresses confusion, hits a difficulty, reports a bug, or suggests an improvement while working in this MCP client.' No alternative tool exists in the sibling set, so no exclusion routing is needed.

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 no annotations, the description carries the full burden and does so richly: it discloses that no file bytes flow through the model context, that the first sync replaces starter files with the remote's default branch, credential requirements per host type, and a detailed catalogue of failure reasons (token_required, address_blocked, network_error, credential_mismatch, timeout, unrelated_history) with guidance on whether the remote remains configured.

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

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

The core purpose is front-loaded well, but the body is a very long, dense run-on covering many error reasons with some repetition (repeated 'the remote IS configured' phrasing). Most content is useful, but it is over-sized and hard to scan.

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

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

An output schema exists so return values need not be explained, and the description covers prerequisites, alternatives, side effects, and error handling comprehensively. The only real gap is that the single project_id parameter is never explicitly described.

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 0% and there is one parameter (project_id), whose meaning is only implied through repeated references to 'this project's workspace' and 'this cloud project'. The description doesn't explicitly state that project_id selects the sync target, but the intent is reasonably inferable from context.

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: pull the configured remote git repository into this project's workspace, equating it to the web app's pull button. It explicitly distinguishes itself from write_file/upload_file (no file bytes through model context) and routes to get_git_status for context, so an agent can tell it apart from siblings.

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

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

Gives clear when-to-use ('user has a local/remote git repository they want reflected'), prerequisites (attach remote first via web app or REST PUT, no unsaved local edits, check get_git_status first), and explicit when-not guidance around re-attaching remotes for various error reasons.

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 no annotations, the description carries the full burden, and it does disclose the key dependency: a prior compile and the existence of output.synctex.gz. However, it says nothing about failure behavior when the file is missing, coordinate validity, or whether it is a pure read. Useful precondition context, but not rich behavioral disclosure.

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 with the core purpose front-loaded, then usage, then prerequisite. No filler and every sentence contributes 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?

An output schema exists, so return values need not be explained. Purpose, direction, and the compile prerequisite are covered; the only real gap is the undocumented coordinate parameters, which keeps it short of 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 0% across 5 parameters (project_id, page, x, y, pdf_filename), yet the description gives no per-parameter meaning. It never clarifies that x/y are PDF point coordinates, that page is a page index, or what pdf_filename (default output.pdf) selects, so the low-coverage gap is not compensated.

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 ('Resolve'), resource ('PDF coordinates to source file and line'), and mechanism ('via SyncTeX'), plus an explicit direction arrow '(PDF → source)'. This direction marker cleanly distinguishes it from the sibling synctex_forward without needing to open either schema.

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

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

Explicitly says when to use it ('Use after a compile to map a click position back to the .tex line') and states the precondition ('Requires a prior compile (needs output.synctex.gz)'). It does not name synctex_forward as the inverse alternative for the opposite direction, but the 'PDF → source' framing implies it.

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 no annotations, the description carries the full behavioral burden. It discloses the return shape (page + x/y + width/height) and the compile prerequisite, which is useful. It does not cover failure modes (unsynced line, missing file) or permission needs, so coverage is adequate but not complete.

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

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

Two tight sentences with no waste; the core purpose and return value are front-loaded, and the prerequisite trails as a short caveat. Every sentence earns its place.

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

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

An output schema exists, so the return-format mention is a bonus rather than a necessity, and the compile prerequisite is helpful. But for a 5-parameter tool with 0% schema coverage, the description omits context on column, pdf_filename, and project_id, leaving the calling contract under-specified.

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 0% across 5 parameters, so the description must compensate, and it only implies 'file' and 'line'. It says nothing about 'column' (optional), 'pdf_filename' (defaults to output.pdf), or 'project_id', leaving three parameters undocumented anywhere.

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 ('Resolve') and resource ('source file/line to the PDF highlight rectangle'), and the '(source → PDF)' directional marker effectively distinguishes it from the synctex_backward sibling without needing to name it. An agent can tell the two apart at a glance.

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?

Provides one concrete prerequisite ('Requires a prior compile'), which is genuine usage context. However, it never names synctex_backward or states when to pick this direction over the reverse, leaving alternative selection to inference from the arrow notation.

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?

No annotations are provided, so the description carries the full burden and it does disclose real side effects: the project reappears in the default listing and again counts against the quota. It omits permission/auth requirements and any error behavior for invalid ids, but the quota/visibility consequences are solid behavioral disclosure beyond the schema.

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

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

Two sentences, each earning its place, with the core action and its effect front-loaded before the discovery tip. No filler or redundancy.

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

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

An output schema exists, so return values need no explanation, and the description covers the state change, quota effect, and id-discovery path. For a single-parameter restore tool this is sufficient for an agent to invoke 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?

There is one required parameter (project_id) with 0% schema description coverage, so the description must carry the meaning. It indirectly explains where an id comes from (list_projects with include_archived=true) but does not state the id format or that it must reference an archived project, leaving a gap.

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 ('Restore an archived project') in the first clause and immediately distinguishes it from the inverse sibling archive_project by describing the resulting state change. An agent can identify its role 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?

Implies the usage context (reversing an archive) and adds a concrete operational tip: pass include_archived=true to list_projects to obtain archived project ids. It lacks an explicit 'when-not-to-use' condition, e.g. handling of projects that were never archived, keeping it 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?

With no annotations, the description carries the full behavioral burden and succeeds: it lists allowed extensions, states the ~22.5MB raw-byte ceiling from the 30MiB transport body limit, warns oversize calls are rejected with an opaque 413 before the tool runs, and flags the context cost of looping over binaries.

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

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

Three dense sentences that are front-loaded with the core action before constraints and alternatives. The size/transport explanation is slightly verbose but every clause conveys actionable constraints, so 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?

An output schema exists so return values need no explanation, and the description covers limits, extensions, and alternatives well. The only shortfall is that mime and project_id receive no semantic treatment.

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 0%, so the description must compensate. It adds real meaning for content_base64 (base64 encoding, size cap) and implies path semantics, but project_id and especially the mime parameter (default '') are never explained anywhere, leaving a gap.

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

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

States a specific verb and resource ('Write a binary asset into the project from base64-encoded bytes') and immediately distinguishes its niche from siblings by declaring it 'the only way to deliver an image for \includegraphics'. An agent can tell it apart from write_file and sync_from_git 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 routing rules for alternatives: text files use write_file, directories/many binaries should use sync_from_git, and oversize assets go through the web app. Both inclusion and exclusion conditions are given, 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the 20MB raw-byte limit, the base64 encoding requirement, and that the result is a new paper_id. It omits permissions/auth requirements, dedup or overwrite behavior on upload, and error conditions for oversized or malformed input.

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, front-loaded with the core action and constraint, then the routing rule. No 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?

Although an output schema exists (so return values needn't be detailed), the combination of zero schema coverage, no annotations, and three undocumented parameters leaves the definition incomplete for a mutation tool that writes to the user's library.

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 0% across 4 parameters. The description compensates for only content_base64 (base64 encoding, 20MB cap); tags, filename, and folder_id are wholly undocumented in both schema and description, leaving most parameters unexplained.

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+destination ('Upload a PDF ... into the user's paper library'), and names the related siblings (search_papers, read_paper) so it is distinguishable from the generic upload_file. An agent knows exactly what this does without opening the schema.

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

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

Gives an explicit trigger and sequencing rule: 'Use after search_papers when the user wants a found PDF in their library for read_paper.' This is a clear workflow context, though it does not state when NOT to use this versus upload_file or what to do if the PDF already exists.

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?

No annotations are supplied, so the description carries the full behavioral burden. It does not disclose whether validation is read-only, whether it may modify the project or bib file, what counts as 'complete', or what errors it can raise; the only signal is the word 'validate'.

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, front-loaded sentence with no filler or repetition. It is efficient, though its brevity borders on under-specification rather than true 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?

An output schema exists, so return values need not be explained, but with no annotations, zero parameter documentation, and no usage context, the description is too thin for a tool whose failure modes and side effects are unknown.

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 0%, so the description must compensate, but it mentions neither 'project_id' nor 'bib_file'. The default references.bib in the schema is undocumented, and the description gives no clue about acceptable IDs or file selection.

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 (validate) and resource (citation completeness) scoped to a LaTeX project, so the agent knows exactly what the tool does. It does not, however, differentiate itself from any sibling or note how it differs from compile/compile_log, which also touch LaTeX projects.

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

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

There is no indication of when this tool should be invoked versus alternatives, no prerequisites (e.g., must the project already be uploaded/compiled?), and no exclusions. The agent must infer all usage context from the one-line purpose.

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 no annotations, the description carries the full burden and discloses several non-obvious traits: full replacement semantics, the diff/cost/mistyping consequences of over-rewriting, and that session-branch writes create a pending review change needing apply/discard. It does not cover failure modes, permissions, or what happens to the file on a rejected review, leaving a modest 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?

The verb and scope lead the paragraph, alternatives follow, and the rationale plus session-branch caveat close it. Every sentence carries distinct information with no restatement of the tool name or schema.

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

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

For a write tool with an output schema present, return values need not be explained, and the description covers purpose, selection rules, cost consequences, and session-branch review behavior. The remaining gap is parameter-level guidance for path/project_id/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 0% across 4 parameters, so the description must compensate. It clarifies the semantics of 'content' (complete content, wholesale replacement), but says nothing about 'path' format, 'project_id', or the optional 'description' parameter, leaving three of four undocumented.

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

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

The description states a specific verb and resource ('Write a file's COMPLETE content, replacing whatever is there') and immediately scopes it against siblings. An agent can distinguish it from edit_file and append_to_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?

It gives explicit when-to-use ('only to create a new file or to rewrite one from scratch') and names both alternatives with the condition that selects each ('To change part of an existing file use edit_file, and to add to the end use append_to_file'). Nothing about tool selection 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.