PaperDock

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

The description adds substantial behavior beyond the annotations: required compile:run and Owner/Editor access, caching and active-job reuse, queueing under existing limits, and immediate return without waiting. It also clarifies side effects, stating that it creates job/artifact/history checkpoints without changing source files or deleting artifacts, and that it does not publish publicly or send to external recipients.

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

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

The description is dense but front-loaded, starting with the core action and entry path before moving into usage, permissions, caching, async behavior, and side effects. Every sentence contributes operational context that helps an agent invoke the tool correctly.

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 an asynchronous compilation tool with an output schema, the description covers the essential context: permissions, caching/reuse behavior, queueing, immediate return, follow-up via read_pdf, and side-effect boundaries. It is complete enough for an agent to understand both how to call it and what will happen after calling it.

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 schema already documents the path parameter, and the description reinforces it as an explicit entry .tex path. The projectId parameter has no schema description, and the description only implies project context through phrases like server-saved project files and project compiler settings rather than explaining the projectId parameter directly.

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: compile a PDF from server-saved project files using project compiler settings and an explicit entry .tex path. It clearly distinguishes this from read_pdf by explaining that compile_pdf starts the job while read_pdf is used for progress and retrieving the PDF.

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

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

It gives explicit when-to-use guidance: when the user asks to compile or needs a current PDF. It also explicitly rules out automatic use after every source edit and names read_pdf as the follow-up tool for progress and results.

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

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

Goes well beyond the annotations: it discloses that the comment is posted immediately to collaborators and that later deletion cannot undo prior delivery or reading — this explains WHY destructiveHint=true even though no file content is modified, which annotations alone would leave confusing. It also pre-empts the read/write ambiguity with 'without changing the source file'. It doesn't cover permission requirements or limits on later edits.

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?

Four short sentences, purpose front-loaded, then the side-effect warning, then the targeting constraint. Dense but every sentence carries information; the ordering puts the most decision-relevant facts first.

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 9-parameter mutating tool with an output schema (so returns needn't be described) and annotations that already flag destructive=true, the description supplies the crucial non-obvious facts: immediate delivery, irreversibility of that delivery, no source modification, and the exclusive target rule. Gaps in context/offset parameter meaning keep it from a 5.

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 has to carry the load. It usefully documents the fileId/path mutual exclusion (the oneOf) and the quote-to-selection-offset inference, covering the most confusing parameters. However, body constraints (4000 chars), projectId's role, contextBefore/contextAfter, and selectionFrom/selectionTo range semantics are left entirely to their bare names.

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 (Create) plus resource (an open Comment) and adds meaningful scope: 'on a .tex project file' and 'without changing the source file'. This clearly separates it from edit_file/create_file style writes, though it never explicitly distinguishes itself from the sibling reply_to_comment.

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 line 'Provide exactly one target: fileId or path' is a genuine usage constraint, and 'Selection offsets may be inferred from quote' tells the agent it can skip offset params. But there is no guidance on when to use this versus reply_to_comment or list_comments, and no prerequisites named.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds genuinely new behavior: collision is non-destructive and fails rather than overwrites, and empty content is a valid, meaningful input. It does not say what the response looks like, but an output schema exists.

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

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

Three short sentences: what it does first, then the empty-file edge case, then the collision constraint. No filler and no repetition of the title.

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

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

An output schema exists so return values need not be described, and the annotation profile covers safety. The only real gap is the undocumented projectId, which an agent must infer from sibling tools that share the parameter.

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 carry the load. It does explain 'content' well (supplied text, empty string permitted and required) and 'path' as a new project path, but 'projectId' is never mentioned, leaving one of three required parameters defined only by its uuid format.

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

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

States a specific verb and resource ('Create a new editable text file') plus the source of the data ('supplied content'), which implicitly separates it from upload_file and read_file. It never names a sibling, so differentiation is inferred rather than explicit.

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?

'Existing paths are never overwritten' and 'Pass an explicit empty string to create an empty file' give the agent concrete usage context: collision means failure, so an existing path requires edit_file instead. It stops short of naming edit_file as the alternative, which would make this a 5.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=false); the description goes well beyond them by disclosing uniqueness semantics (case- and whitespace-insensitive per owner), a specific error code, and a no-retry/no-modify policy. That is exactly the mutation-context an agent needs and cannot get from the annotations or 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 action and the gating condition, then proceeds in priority order through error handling and escalation. The closing sentence partially restates the no-retry guidance, but the redundancy is intentional for a destructive-adjacent operation and costs little.

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

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

With an output schema present, return values need not be described. For a one-parameter create tool, the description covers invocation conditions, collision behavior, and user-consent boundaries — nothing an agent needs in order to call it safely is missing.

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

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

The single parameter has no schema description (0% coverage), but the description compensates by defining name normalization rules — uniqueness is per owner and ignores case and leading/trailing spaces — which directly affects how the agent should construct and compare names. It doesn't cover the 120-char bound explicitly, but the schema supplies that.

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 PaperDock project') and adds the scope of what the call produces ('with a starter main.tex'). This is clearly distinguishable from sibling tools like create_file, list_projects, and create_comment.

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 gating condition ('only when the user explicitly asks') plus a concrete error-recovery path: on PROJECT_NAME_ALREADY_EXISTS, do not retry, call list_projects instead, and ask the user if intent is unclear. Alternatives and when-not-to-use are named directly rather than implied.

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

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

Beyond the annotations, the description discloses substantial behavior: the edit is applied immediately, the change is recorded for review, rangeTokens are bound to connection/file/revision/range/content and expire after 10 minutes, apply sessions can merge unrelated edits, and specific error codes indicate temporary deferral versus unknown outcomes. This is unusually rich behavioral disclosure for a destructive 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?

The definition is front-loaded and nearly every sentence carries operational meaning, including retry and error-handling rules. However, the single dense paragraph, long error-code sequence, and compressed terminology make it harder to scan than it could be with lighter structure.

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 complex destructive edit tool with ten parameters and many failure modes, the description covers the critical workflow, conflict handling, idempotency, review integration, and retry semantics. An output schema exists, so return-value explanation is not required, and the remaining gaps are minor relative to the complexity addressed.

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 only 10%, so the description has to carry most parameter meaning. It successfully explains the exactly-one target rule for fileId or path, the exactly-one payload rule for operations, content, or rangeToken with insert, the role of baseRevision, exact expectedText copying, empty expectedText for insertions, and stable requestId reuse. It leaves projectId, expectedUpdatedAt, and precise from/to boundary semantics unstated.

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

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

The description opens with a specific verb and resource: immediately edit one existing editable text file. It also states the side effect of recording the change in PaperDock's Review changes UI, and it explicitly excludes create, rename, and delete, which distinguishes it from sibling tools such as create_file and rename_file.

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

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

It gives explicit selection rules among the payload alternatives: use rangeToken with insert for a long replacement from an exact read_file.lineRange call, operations for other focused edits, and content only when broadly rewriting most of the file. It also tells the agent to read first and pass baseRevision, and it explains when to reread instead of retrying blindly.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds only that results are chronological and recent; it does not mention limits, defaults, pagination, permissions, or other operational behavior. With annotations covering the main behavioral traits and an output schema covering returns, a 3 is appropriate.

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 wasted words. It is concise, though its terseness contributes to the missing parameter and usage guidance.

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?

This is a simple read tool with annotations covering safety and an output schema covering return values, so the description does not need to explain those. However, with 0% parameter description coverage, the description should at least clarify projectId scope and limit/pagination behavior; 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 explain either parameter. 'Project chat messages' weakly implies projectId, but the optional limit parameter, its maximum of 200, and its default/behavior are not addressed at all.

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 (Read), resource (project chat messages), and ordering (chronological), so the core operation is clear. It does not explicitly distinguish itself from nearby tools such as send_chat_message or list_comments, which keeps it from 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 word 'recent' implies that this tool is for retrieving recent chat history, but the description gives no explicit when-to-use guidance, no exclusions, and no alternatives. It also does not explain when to use the optional limit or how pagination works.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so safety is covered. The description adds real behavioral information beyond that: only active threads are returned and resolved history is excluded, which directly affects what the agent can conclude from an empty result. It omits ordering and pagination, keeping it short of a 5.

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

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

Two sentences, zero filler, and the scope constraint is front-loaded immediately after the core action. 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 return-shape detail is unnecessary, and annotations cover the safety profile. The remaining gap is whether replies to resolved parents appear, and whether results are paginated or ordered — minor but relevant for a listing tool.

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

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

There is one parameter (projectId) with 0% schema description coverage, so the description must compensate. "Project comments" implies the id scopes the listing to a project, but it adds nothing about format, requiredness, or behavior for invalid ids. With a single, obvious parameter and a uuid format in the schema, baseline 3 is appropriate.

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

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

States a specific verb and resource ("List active project comments and their replies") and adds a scope qualifier that separates it from generic listing tools. It does not explicitly contrast with siblings such as list_chat_messages or list_files, but the resource noun is distinct enough to disambiguate.

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 sentence "Resolved comment history is not returned by this tool" gives an implicit when-not, and the word "active" signals the intended scope. However, no alternative tool is named for retrieving resolved threads, so the agent must infer where to go next.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful behavioral note that contents are not loaded, but says nothing about pagination, ordering, or permissions for a project that may 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 front-loaded sentence with zero waste. The metadata-only constraint is stated immediately and nothing is repeated from 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 explained, and the read-only annotations cover safety. However, for a listing tool the description omits pagination behavior, result ordering, and any projectId semantics, leaving meaningful gaps.

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 single required projectId parameter has no description in the schema or the tool description. "Project file" weakly implies projectId scopes the listing, but the UUID format and required nature are not explained by the 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 ("List project file metadata") and distinguishes itself from read_file by clarifying it does not load full file contents. It does not explicitly differentiate from the sibling search_files, so it falls just short of a 5.

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

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

The phrase "without loading full file contents" implies this is the lightweight alternative to read_file, but no explicit guidance is given about when to use search_files instead or any preconditions. Usage must be inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description goes beyond them by disclosing what each entry carries (current role and effective MCP capabilities) and by imposing a presentation rule about projectId, which is real behavioral context an agent would otherwise lack.

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

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

Two sentences, zero filler. Scope comes first, then the output-handling instruction, so the agent gets the actionable constraint before it ever sees the results.

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

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

With an output schema present, return-value detail is already covered, and the description supplies the one thing the schema cannot: how to treat projectId downstream. Nothing needed to select or invoke this call correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to explain about inputs; the baseline of 4 applies. It correctly avoids restating the empty schema.

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

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

The description uses a specific verb and resource ("List standard PaperDock projects accessible to the connected account") and disambiguates it from the file/comment/chat siblings, which all operate within a project. The qualifier "standard" hints at other project types but never names them, so a small ambiguity remains.

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 tells the agent how to use the output — "Use projectId only for subsequent tool calls and do not show it unless explicitly requested" — which effectively positions this as the entry-point call that supplies IDs for the rest of the toolset. No sibling alternative exists to route against, so the absence of explicit exclusions is not a real gap.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, but the description adds material context beyond them: implicit folder creation is allowed, changes bypass the Review changes Keep/Revert flow, no read_file or binary download is needed, and text references (LaTeX/bibliography, relative paths) are NOT auto-updated. These are non-obvious consequences an agent would otherwise have to discover by trial.

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 purpose is front-loaded and every sentence carries information, but nine sentences is heavy for a four-parameter tool, and a few clauses repeat schema content (the empty-folder convention, revision sourcing). The reference-checking and retry-once guidance could be tightened without information loss.

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

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

With an output schema handling return values, annotations covering the safety profile, and 75% schema coverage, the description fills the remaining gaps: side effects on Review changes, the missing-reference-update risk, and the conflict-recovery procedure. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 75% and the schema already documents path, baseRevision and destinationFolder (including the empty-string-means-root convention), so the description largely reinforces rather than adds. It does add some value: 'New implicit folders are allowed' tells the agent that a non-existent destinationFolder is not an error, and it stresses passing the exact revision. Marginal gains, but real ones.

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

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

Opens with a specific verb, resource and scope ('Move one existing text or binary file to a project-relative folder in the same project, preserving its filename and contents'). It also explicitly distinguishes itself from the closest sibling: 'rename_file preserves the directory and extension; move_file preserves the filename within the same project.' An agent can route between move_file and rename_file without opening either schema.

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

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

Gives explicit when-to-use ('move_file only when the user requests a file rename or move'), prerequisites ('Call list_files first and pass the exact path and its revision as baseRevision'), a follow-up requirement for references via edit_file, and a recovery path ('On a missing path or revision conflict, call list_files and confirm the target before retrying once'). It also names exclusions: no overwrites, folder moves, cross-project transfers or binary content 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?

Annotations only say readOnly/openWorld=false; the description adds the operationally critical facts: the URL is signed and expires in 10 minutes, ranges are capped at 400 lines, offsets are absolute UTF-16, and rangeToken is revision-bound. The revision-bound token is exactly the kind of silent-failure constraint an agent needs disclosed.

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 what the tool does and the one-target rule, and each subsequent sentence adds a distinct constraint (cap, token semantics, edit_file handoff, omit case). It is on the dense side and the rangeToken handoff sentence takes effort to parse, but there is no filler.

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

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

An output schema exists, so return shape needn't be described, and the description still flags the non-obvious return artifacts (signed URL expiry, rangeToken). For a 4-param tool with a nested lineRange object and a 400-line cap, nothing an agent needs to call it correctly is missing apart from projectId.

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 carries the burden, and it does for most of it: the fileId/path oneOf is explained, and lineRange's startLine/endLine are clarified as inclusive and 1-based with a 400-line cap. The required projectId parameter is never mentioned at all, leaving one real 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 ('Read an editable project file') and immediately covers the second mode (signed download URL for private assets), which distinguishes it from list_files/search_files. It also names edit_file as the counterpart for the rangeToken handoff, so an agent can separate read from write 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?

Gives an explicit exclusivity rule ('Provide exactly one target: fileId or path'), explicit when-to-use for lineRange ('localized task in a large text file'), an explicit when-not ('Omit lineRange when the full file is required'), and an explicit refinement rule ('Refine lineRange first when only part of the returned range should change'). This is the when/when-not/alternative pattern at full strength.

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

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

Goes well beyond the readOnly/non-destructive annotations: link validity capped at 10 minutes, private access, diagnostics report is five-minute and filtered (never raw log), downloads recheck connection and project access, unsaved browser edits excluded, and a security warning to treat diagnostics as untrusted data. The 'never compiles, waits, or polls internally' claim directly informs caller behavior.

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 both addressing modes are front-loaded, and most sentences carry distinct operating rules. It is dense and long, with some procedural guidance (polling limits, open before discussing) that could be trimmed, but nothing is filler.

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

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

Output schema covers return values, annotations cover safety, and the description still supplies the operational contract an agent needs: freshness semantics, retry policy, diagnostics opt-in, staleness reporting, and the untrusted-data caveat. Nothing material is missing.

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

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

Schema coverage is 75% and the description still adds meaning: path is an entry .tex path not a PDF path/URL, jobId checks only that job with no fallback, and includeDiagnostics is scoped to troubleshooting with a non-raw output. Slight overlap with schema parameter descriptions keeps it from a 5.

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

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

States a specific verb-plus-resource ('Read the latest successful PDF') and gives both addressing modes (entry .tex path or jobId from compile_pdf). It explicitly distinguishes itself from compile_pdf and read_file, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use branches: missing/outdated PDF → compile_pdf then read_pdf with jobId; includeDiagnostics only when troubleshooting or asked; uploaded PDFs → read_file; queued/running → respect retryAfterSeconds, check at most 5 times. This is a full when/when-not/alternatives map.

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

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

Beyond the destructiveHint=true annotation, the description discloses concrete consequences: no overwrites, folder moves or cross-project transfers, immediate path changes outside the Review changes Keep/Revert flow, and that text references (LaTeX, bibliography, relative paths) are not auto-updated and must be fixed with guarded edit_file and reported separately. That is exactly the kind of side-effect detail annotations cannot convey.

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

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

Front-loaded with purpose and the sibling distinction, then prerequisites, constraints, and failure handling in a logical order. It is dense but most sentences carry non-obvious operational information; there is mild redundancy between 'preserving its extension and contents' and 'preserves the directory and extension.'

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 annotations cover the safety profile, so the description only needs to carry workflow, constraints, and side effects — all present, including reference-update fallout and retry protocol. Nothing an agent needs 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?

With 75% schema coverage the baseline is already high, but the description adds real meaning: newName must match the existing extension and contain no folder path, baseRevision comes from list_files and needs no read_file or binary download, and path must be the exact current project-relative path. Only projectId gets no additional treatment.

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 (rename) and resource (one existing text or binary file in its current folder) with explicit scope limits: directory and extension preserved, contents untouched. It explicitly distinguishes itself from move_file, so an agent can separate the two without opening either schema.

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

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

Gives an explicit positive trigger (user requests a rename), a named alternative (move_file) with its differing behavior, and a prerequisite workflow (call list_files first and pass the exact path plus revision). It also prescribes recovery behavior on missing path or revision conflict: call list_files, confirm, retry once.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses who sees the reply ('visible to project collaborators'), that it is posted immediately, that it is attributed as agent-created, and that later removal cannot undo prior delivery or reading — real context for a destructive write. The no-retry instruction also prevents a common failure loop that annotations cannot express.

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

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

The action and target are front-loaded, then id sourcing, then the failure-handling rule, then visibility and body style — a sensible ordering with almost no filler. It is slightly dense across four sentences, but each one adds a distinct operational constraint.

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?

A destructive write tool with an output schema, so return values need no explanation; the description covers visibility, attribution, irreversibility, and the failure path. The main remaining gap is projectId semantics and any permission/auth requirement for replying in a given project.

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, so the description must carry the burden. It explains commentId's provenance and how to write body, but projectId is never mentioned, so a third of the parameters remain semantically 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 ('Post a reply ... to an open Comment') and names the connected account, which is far more precise than the title alone. It implicitly separates itself from the sibling create_comment by requiring an existing open Comment and a commentId, but never explicitly contrasts the two, leaving that inference to the agent.

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 tells the agent exactly where commentId comes from (a value returned by list_comments or copied from PaperDock) and gives an explicit recovery rule: if the Comment is not found, call list_comments once and do not retry the same missing commentId. It also adds a writing guideline ('natural, collaborator-facing prose'), so the invocation path and message style are both prescribed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that: case-insensitive matching and the shape of the results (paths, positions, revisions, short snippets). It omits any note on result caps or truncation behavior when limit is hit.

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 zero waste; the search scope and the sibling routing come first, and the fallback to read_file closes it out.

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

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

An output schema exists, so explaining return values is optional and the mutation/safety burden is light for a read-only tool. However, the undocumented extensions and limit parameters leave a real gap for an agent trying to call it precisely.

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 carry parameter meaning, but it only loosely characterizes 'query' through examples. The 'extensions' filter and 'limit' (capped at 50) are never mentioned, leaving two of four 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 ('Find where ... appears') and resource ('across editable project files'), and enumerates the query types it accepts. It also distinguishes itself from read_file, so an agent can tell the two apart 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 an explicit when ('when its file or location is unknown') and an explicit when-not with the named alternative ('If the target file is already known, use read_file directly instead'). Nothing is left to inference.

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

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

Adds real context beyond the annotations: the message is tagged as agent-created, is delivered immediately and visible to project members, and later edits/deletions cannot undo delivery or reading. That explains why destructiveHint=true in a way the annotation alone cannot. It still omits failure modes (e.g. what happens on a bad projectId or an oversized body).

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 dense, front-loaded sentence that leads with the action and target, then tacks on the delivery warning. No filler, though the trailing irreversibility clause is slightly buried in a comma chain rather than separated.

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 annotations carry the safety profile, which the description reinforces. For a 2-parameter mutation it covers target, visibility, and irreversibility well; the gaps are parameter meaning and error behavior rather than missing core context.

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 never names or characterizes either parameter. 'Selected private PaperDock project' loosely gestures at projectId, but the body parameter, its 4000-character cap, and the uuid format are left entirely to the schema with no semantic gloss.

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

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

Specific verb + resource: 'Post a message ... to the selected private PaperDock project's Chat.' Scope (which project, which surface) is clear enough to distinguish it from list_chat_messages and from comment tools. It stops short of explicitly naming the sibling surfaces it is not (create_comment, reply_to_comment).

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: the agent must infer that posting requires a project the account already belongs to and that thread-style replies belong to reply_to_comment instead. No when-to-use, when-not-to-use, or prerequisite conditions (membership, connected account) are stated outright.

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

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

Annotations already mark the tool as destructive and open-world, and the description adds crucial behavior: existing paths return confirmation_required without changing files, awaiting_upload is not success, uncertain transfers should be checked at most twice, and upload authorization headers must never be exposed. It also clarifies that expectedRevision and replacementTarget are preconditions, not server-verified human approval.

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 long but front-loaded with purpose and mode selection, then proceeds through safety-critical transfer and overwrite rules. Most sentences carry necessary operational detail, though the density is high and some warnings could be tightened.

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 complex oneOf schema, 13 parameters, destructive annotation, and critical binary-transfer workflow, the description supplies the missing operational context: approval flow, conflict handling, retry limits, success states, and security constraints. An output schema exists, so it does not need to explain return values.

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 only 38%, but the description compensates by explaining the key mode-selection parameters, transfer semantics, size limit, overwrite approval requirements, expectedRevision conflict handling, replacementTarget meaning, and uploadId use. Some parameters such as sha256 and mimeType are not explained in prose, so it is strong but not exhaustive.

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

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

The description gives a specific verb and resource and distinguishes upload_file from create_file and edit_file: new UTF-8 text uses content, existing text must use edit_file, and binary replacement uses upload_file with an approved transfer. It also defines the scope as new file or explicitly approved binary replacement.

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

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

It explicitly routes between content, contentBase64, transfer: direct, transfer: web, file attachments, uploadId checks, and edit_file. It also states the overwrite approval sequence and when to stop and ask again rather than refreshing the revision.

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