PaperDock

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

The description discloses immediate posting, no source modification, and irreversibility of delivery/reading—side effects that go beyond the annotations (destructiveHint: true). This fully informs the agent of the tool's consequences.

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 compact—two sentences—and well structured, covering action, side effects, and constraints without redundancy or irrelevant detail.

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?

The description captures core behavior and some constraints, but omits details about the output schema (which is present) and does not fully explain the remaining parameters. It is adequate for basic use but incomplete for nuanced invocation.

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 description explains key parameters (fileId/path as exclusive targets, quote for inferring offsets) but leaves many others (selectionTo, contextBefore, contextAfter, selectionFrom) without any explanation. With schema coverage at 0%, the description fails to substantively clarify most parameters.

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 ('Create ... and post'), resource ('Comment on a .tex project file'), and scope ('to project collaborators') without ambiguity. It clearly distinguishes from sibling tools like reply_to_comment and list_comments.

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 explicitly notes that the action does not change the source file, warns that deletion cannot undo delivery/reading, and instructs to provide exactly one target (fileId or path). These are concrete usage conditions that guide when and how to invoke the tool.

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

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

Discloses a key behavior: existing paths are never overwritten, and that an explicit empty string creates an empty file. This goes beyond the minimal annotations, though it does not describe error behavior or side effects beyond creation.

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 concise sentences convey the core action, the empty-file special case, and the no-overwrite guarantee. 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?

The description covers the main creation behavior and the no-overwrite constraint, but it does not explain what happens when the path already exists (e.g., error vs. no-op), which is a meaningful gap for safe invocation.

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 description explicitly explains the content parameter (including empty string behavior) and partially clarifies path as a project path, but projectId is not described beyond its name. With 0% schema coverage, this is only partial compensation.

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?

Clearly states it creates a new editable text file at a project path from supplied content, and explicitly notes that existing paths are never overwritten. This distinguishes it from sibling tools like edit_file and replace_file.

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

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

The description implies usage for new files by emphasizing 'new' and 'never overwritten', but it does not explicitly direct users to edit_file or replace_file for existing paths. The guidance is helpful but mostly implicit.

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 side effects (creating a starter main.tex), name normalization and uniqueness semantics, the no-retry rule, and the no-modification/no-rename-without-authorization constraint. There is no contradiction with readOnlyHint=false, and the destructiveHint=false is consistent with creation rather than destruction.

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 four sentences long but every sentence carries distinct operational guidance; there is no filler. Core purpose is front-loaded, and policy details are organized in a logical sequence.

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 creation tool with an output schema present, the description covers purpose, usage constraints, uniqueness, error handling, and authorization. An agent has enough information to decide when to call it and how to behave on failure without needing to inspect additional docs.

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 only provides the name parameter with min/max constraints, so the description needs to add meaning for it. It does so by explaining case-insensitive and whitespace-insensitive uniqueness per owner, which is important for choosing and reusing names. A small gap is that it doesn't explicitly restate that 'name' is the project's display or identifier name, but that is readily inferable.

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 concrete verb-resource pair: creating a new PaperDock project with a starter main.tex. It also adds a scope qualifier ('only when the user explicitly asks') and the uniqueness behavior, which makes it distinguishable from sibling creation tools like create_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 when-to-use guidance ('only when the user explicitly asks') and provides a detailed failure-handling policy: don't retry on PROJECT_NAME_ALREADY_EXISTS, do call list_projects, and ask when intent is unclear. It also tells the agent never to modify an existing project or rename without authorization.

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 description thoroughly discloses behavior beyond the destructiveHint annotation: it records changes in Review UI, requires reading current content first, retries once on conflict, and explains the connection/file/revision/range/content-bound nature and 10-minute expiry of range tokens. No contradiction with annotations 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?

The description is dense but every sentence adds practical information. It is front-loaded with the main purpose and then organized by edit mode, limitations, and conflict handling, making it effective despite its length.

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 schema's complexity and 0% parameter description coverage, the description covers all important usage modes, token semantics, conflict retry behavior, and constraints. It provides enough context for an agent to invoke the tool correctly without ambiguity.

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 0% schema description coverage, the description compensates well by explaining fileId vs path, operations, content, rangeToken+insert, expectedText, baseRevision, and the meaning of insert. projectId and expectedUpdatedAt are not explicitly described, but the core parameters are well covered.

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 clearly states the tool's purpose: immediately edit one existing editable text file and record the change in PaperDock's Review UI. It distinguishes itself by noting it cannot create, rename, or delete files, making its scope unambiguous.

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 strong guidance on when to use each edit mode (operations, content, rangeToken) and describes conflict handling and token expiration. However, it does not explicitly contrast edit_file with the sibling replace_file tool, so the choice between those two alternatives is not fully 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?

The description matches the readOnlyHint annotation by saying 'Read', and no side effects are mentioned. However, it does not add rich behavioral context beyond the annotations, such as error conditions, data limits, or ordering guarantees other than 'chronological'.

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, focused sentence that leads with the verb and resource. It contains no redundant phrasing or unnecessary details, making it highly concise and well-structured.

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?

While an output schema exists, the description leaves key aspects unexplained, such as the meaning of 'recent' (time window vs. count) and the purpose/behavior of the 'limit' parameter. This makes the tool incomplete for an agent trying to invoke it correctly without additional 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 provides no explanation of the 'limit' or 'projectId' parameters. Since coverage is extremely low, the description was expected to compensate by explaining parameter meaning, but it does not.

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 clearly states the verb 'read', the resource 'project chat messages', and the scope 'recent... in chronological order'. It is distinguishable from sibling tools like send_chat_message or list_comments based on the resource and action.

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 implies usage for reading chat messages but does not explicitly contrast with alternatives like list_comments or send_chat_message. There is no 'use this when' or 'instead of' guidance, so the agent must infer the appropriate context from the resource 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safe, non-mutating nature is known. The description adds useful behavioral context by making the active-only filtering explicit, without contradicting the annotations.

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

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

The description is two short sentences and is tightly focused on the tool's core behavior and exclusion. No filler or unnecessary detail is present.

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?

The description is complete for this simple read-only listing tool, and an output schema is indicated. The active-versus-resolved distinction is the only contextual nuance needed, and it is explicitly provided.

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 only parameter, projectId, is present and required in the schema, but the description does not explain its semantics beyond what the tool title and schema field name imply. With 100% schema coverage, a baseline score of 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?

The description clearly identifies the action (list), the resource (project comments), and the scope (active comments and replies). It also differentiates from sibling tools by specifying that resolved comment history is excluded.

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 explicit guidance on what is returned (active comments and replies) and what is not (resolved history). It does not explicitly name sibling alternatives, but the active/resolved distinction is sufficient for most selection contexts.

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 and destructiveHint, and the description does not add extra behavioral context like sorting, pagination, or side effects. It neither contradicts nor significantly extends beyond annotations, so a neutral score 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, focused sentence with the main action front-loaded. No redundant words or filler, making it highly concise and well-structured.

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 simple nature of the tool and the presence of an output schema, the description is largely complete. It does not need to explain return values since the output schema covers that. However, it could mention what metadata is included (e.g., name, size) but that is not essential.

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

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

With schema description coverage at 0%, the description must compensate for parameter meaning. The single parameter 'projectId' is not explained; although the name is self-explanatory, the description does not clarify what projectId refers to or how it filters results. This is a significant 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 clearly states the action ('List') and the resource ('project file metadata'), distinguishing it from read_file (which loads contents) and search_files (which searches). It is unambiguous and specific.

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 when to use this tool (when metadata is needed, not content), but it does not explicitly name alternatives. This is a clear implicit guideline, though not as explicit as naming sibling tools.

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 and destructiveHint=false, setting a low bar. The description reinforces this by using 'List' and explicitly states what information is returned (role and effective MCP capabilities). It does not mention any side effects or restrictions beyond the output guidance, but given the read-only annotations, this is sufficient.

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 two sentences, front-loaded with the primary action and resource, followed by a concise note on handling the output. Every sentence adds value; there is no fluff or redundant phrasing.

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 parameterless listing operation, the description is complete. It specifies the resource type, the additional output fields (role and capabilities), and gives a practical usage note. The output schema (not shown but present) would cover structural details, so no further context is needed.

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 are zero parameters, and schema coverage is 100% (empty object). The description does not need to explain any parameters, and the absence of param details is not a gap. The mention of projectId being for subsequent calls is about output semantics, not input parameters.

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 verb 'List' clearly indicates a read-only operation, and the resource 'PaperDock projects' is specific. The description also mentions including the account's role and effective MCP capabilities, providing additional detail about the output, which makes the purpose unambiguous.

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 practical guidance on how to handle the returned projectId ('use projectId only for subsequent tool calls and do not show it unless explicitly requested'). It does not explicitly contrast with sibling tools like list_files or list_comments, but the scope is clear enough from the resource type, and the guidance on projectId is useful for downstream usage.

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 description adds valuable behavioral details beyond the annotations: the 10-minute expiry of the download URL, the 400-line limit, absolute UTF-16 offsets, and revision-bound rangeToken. This goes beyond the readOnlyHint and provides concrete expectations.

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 sentences, each with a distinct purpose, front-loaded with the core functionality, and no redundant information. The structure flows from general to specific use cases efficiently.

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?

The description covers the main usage scenarios, including the alternative to edit_file, and given the output schema exists, it is complete for an agent to call correctly. Minor gaps like error handling are not specified but are not critical for basic invocation.

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 0% schema description coverage, the description compensates by explaining the oneOf constraint (exactly one target: fileId or path) and detailing lineRange's inclusive 1-based startLine/endLine and its effects. projectId is not explained but is a required UUID and its purpose is self-evident.

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 clearly states the tool reads an editable project file or returns a signed download URL, and distinguishes it from sibling tools like edit_file and list_files by specifying the read-only nature and two distinct output modes.

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 provides explicit guidance on when to use lineRange for localized tasks, when to omit it for full files, and when to pass the rangeToken to edit_file. It does not explicitly exclude list_files, but the purpose is clear and the main alternatives are addressed.

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=true, destructiveHint=false), the description discloses the 10-minute signed-link expiry, freshness uncertainty, possible coexistence with newer failing compiles, and the requirement to actually open the PDF with a PDF-capable tool. This significantly enriches the agent's mental model without contradicting any annotation.

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

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

Although the description is longer than average, every sentence carries distinct operational value: scoping, link expiry, freshness, tool selection, and failure handling. It is front-loaded with the core purpose and contains 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?

The tool has an output schema, so return-value details are already provided structurally. The description covers the remaining essential context: behavior, freshness caveats, expiration handling, and explicit fallback actions, making it complete for safe and correct invocation.

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 only 50%, with projectId lacking a description. The description compensates strongly for the path parameter by clarifying it is project-relative, an entry .tex file, and not a PDF path or URL. However, it does not add semantic guidance for projectId beyond what the schema's uuid format already implies.

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 clear verb and resource: 'Get the latest successful compiled PDF for an explicit entry .tex path.' It also distinguishes itself from the sibling read_file by explicitly stating that read_file is for uploaded PDF assets, so an agent can 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 description provides explicit usage guidance: it never compiles, waits, or polls; if no result exists or it has expired, the agent should ask the user to compile in the web app; and it names the alternative tool read_file for uploaded PDFs. This is strong when-to-use and when-not-to-use 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?

The description mentions the reply is marked as AI-generated and visible to collaborators, and notes that later removal cannot undo delivery/reading. However, it does not clarify the destructive nature (annotations indicate destructiveHint=true) or any side effects beyond visibility, leaving some behavioral aspects implicit.

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 compact, with each sentence contributing meaning. It efficiently conveys purpose, usage hints, and side-effect awareness. Minor redundancy in mentioning 'connected PaperDock account' and 'immediately' could be trimmed, but overall it is well-structured.

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 output schema exists and the description is concise, the main missing context is the exact behavior on missing comments (already partially stated) and any error conditions. It covers the key aspects an agent needs: what to do, what to pass, and what to expect. Slight gaps remain regarding projectId semantics and failure handling.

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 carries the burden. It explains commentId (from list_comments) and body (natural prose), but does not explain projectId beyond its name. It adds some meaning for two of three parameters, but projectId is only self-evident from the name.

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 ('Post a reply') and a resource ('project comment'), clearly distinguishing it from sibling tools like create_comment and list_comments. It also notes the reply is marked as AI-generated and visible to collaborators, adding useful context.

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 implicitly indicates when to use this tool (when replying to an existing comment, using a commentId from list_comments or PaperDock) and provides guidance on handling missing comments (call list_comments once, do not retry). It does not explicitly name alternatives like create_comment, but the context is clear enough.

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 the bar is lower. The description adds concrete behavioral detail by stating it returns matching paths, positions, revisions, and short snippets, which goes beyond the annotations.

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

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

The description is two sentences, direct and free of extraneous detail. It states the core function, the return information, and the alternative usage in a compact, readable format.

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 are specified. The description adds context about the scope (editable project files) and the search result content, but does not mention potential edge cases like no matches or sorting. Given the schema, this is reasonably 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%, so the description must compensate. It explains the query parameter implicitly via the types of text searched, but does not explain limit, extensions, or projectId. No explicit parameter descriptions are provided, leaving significant gaps for an agent.

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?

Clearly states the tool finds text (word, phrase, citation key, label, LaTeX command) across editable project files when location is unknown. Differentiates from read_file by name and explicit condition.

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 explicit guidance: use when location unknown, and directly names read_file as the alternative when the target file is already known. This leaves no ambiguity about when to select this tool.

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

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

Beyond the annotations (destructiveHint, readOnlyHint), the description adds behavioral details: 'immediately', 'marked as created via an AI agent', 'visible to project members', and that 'later editing or deletion cannot undo prior delivery or reading.' This provides extra context about timing, visibility, and irreversibility.

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, dense sentence that packs all necessary information without unnecessary verbosity. It is well-structured and front-loads the primary action.

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 simple schema, the annotations, and the behavioral details, the description is largely complete. It does not mention the output, but an output schema exists (per context signals), so that omission is acceptable.

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 defines body and projectId with types and constraints, but the description only implicitly clarifies their roles (body as the message, projectId as the target project). It does not explicitly explain each parameter's purpose or format beyond the schema.

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

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

The description clearly states the tool's function: 'Post a message ... to the selected private PaperDock project's Chat.' It uses a specific verb ('Post') and differentiates from siblings like create_comment by focusing on chat messages.

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 implies when to use the tool (sending chat messages to a project) but does not explicitly contrast it with alternatives (e.g., create_comment) or state when not to use it. There is no direct 'use this instead of X' 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?

The description adds meaningful behavioral context beyond the annotations: it guarantees existing paths are never overwritten, restricts contentBase64 to UTF-8 text at editable extensions, and explains that binary replacements are unsupported through MCP. This is rich, non-obvious 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?

Four sentences, each carrying distinct information: core action, compatibility constraint, no-overwrite rule, and binary workaround. The most important purpose is front-loaded. Slightly dense but 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?

The description covers the critical operational constraints well, and the output schema reduces the need to explain return values. However, it leaves optional parameter semantics unresolved and does not address the relationship with create_file, so an agent may still hesitate or misroute.

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 does explain content, contentBase64, and path/extension constraints, but mimeType, sha256, and projectId are left undocumented. With six parameters and no schema descriptions, this is a significant 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 clearly states the verb and resource: 'Create one new editable text file from UTF-8 content.' It also distinguishes itself from edit_file by saying existing paths are never overwritten. However, it does not differentiate from the sibling create_file, which is likely a close alternative.

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 explicit direction: use edit_file for existing text and direct users to the PaperDock web app for binary uploads. This provides clear when-not-to-use guidance. It stops short of a full 5 because it never states when to prefer upload_file over create_file.

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