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

Annotations only declare it is not read-only and is open-world; the description adds the crucial behavioral facts: the call is asynchronous (returns a job ID immediately), has a remote-first fallback on timeout/service errors, and requires latexmk plus the selected engine locally. It does not disclose failure surface (compile errors surfacing only via polling) or whether a prior PDF is overwritten.

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, front-loaded with the async contract before the mode details and the polling instruction. Slightly dense phrasing ("for this build PDF and logs") but no wasted sentences.

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

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

No output schema, five parameters, and zero schema descriptions put the burden on the text, which covers the async model and dependencies but omits what the job ID is used for downstream, what rootPath/timeout do, and how build failure is reported. Adequate to invoke, not fully complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only explains mode (auto = Overleaf first, local fallback) and lightly touches compiler ("the selected engine"). rootPath, timeoutSeconds, and projectId are entirely undocumented, leaving three of five parameters undefined in both schema and description.

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

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

States a specific verb and resource ("Start compilation") plus the return contract ("return a job ID immediately"), which distinguishes it from siblings like get_compile_result. An agent can tell this is the kick-off of an async build, not a status check.

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

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

Explicitly routes the agent to "Poll get_compile_result for this build PDF and logs", which names the follow-up step and the sibling. It also explains when the auto fallback kicks in (timeout/service errors). Missing only an explicit statement of when not to use it (e.g., prefer get_compile_result when a build is already running).

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 the mutation safety profile, including non-read-only, non-destructive, non-idempotent, and open-world behavior. The description adds useful behavioral context by specifying that the file is empty and editable and that write_file should be used for content, though it does not explain duplicate-name handling or permission requirements.

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 three short sentences, front-loaded with the core action and followed by key parameter and workflow guidance. Every sentence provides useful information without wasting space.

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

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

For a simple three-parameter creation tool with annotations covering safety and schema providing required fields and patterns, the description supplies the key non-obvious context. It could be more complete about duplicate handling or error conditions, but it is sufficient for 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 description coverage is 0%, so the description needs to compensate. It clarifies that name is a filename rather than a path and that parentFolderId should be omitted for the project root, but it does not explain projectId or add details about parameter formats beyond the schema patterns.

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: create an empty editable text file. It also distinguishes the tool from write_file by clarifying that the created file is empty and should be populated afterward with write_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 clear usage context, including omitting parentFolderId for the project root and using write_file afterward to add content. It does not explicitly state when not to use it versus upload_file or other alternatives, but the main workflow is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds one piece of real behavioral context — text documents are fetched from a fresh live snapshot rather than a cached copy — but it is cryptic about what a "local artifact" actually is (a path? a handle? a stream?) and gives no size, binary-encoding, or failure 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?

Two tight sentences with no filler and the resource type front-loaded. The brevity is not the problem — the missing content is — so it loses only a point for spending its second sentence on a phrase whose meaning is unclear.

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 two-required-parameter, zero-description-coverage download tool with no output schema, the description should clarify the path/project relationship and what the caller receives back. It does neither, leaving the return value and the target of the download undefined.

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 both required parameters, so the description carries the full burden. It never explains what projectId identifies or what path is relative to (project root? repository? artifact store?), which is exactly the ambiguity an agent must resolve before calling.

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

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

The description states a specific verb+resource ("Download a text file or binary attachment") and names the result (a local artifact), which goes beyond the bare name. However, it never distinguishes itself from close siblings like download_project or read_file, so an agent cannot tell which of the three it wants 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?

No when-to-use guidance is given and no alternative is named, despite siblings read_file, download_project, and upload_file forming an obvious decision set. The single hint — attachments versus text files — is implicit at best.

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 this a read-only, non-destructive, open-world operation, so the safety profile is covered. The description adds genuinely useful context: the return is a ZIP archive of complete source, and historyVersion targets project history rather than document OT history. It still says nothing about permissions, download size, or whether historical ZIPs differ structurally from current ones.

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. The two operating modes are stated first and the trickiest semantic pitfall (historyVersion vs OT version) is front-loaded where it is most likely to be read.

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

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

There is no output schema, and the description correctly tells the agent the payload is a source ZIP, which is the key return-value fact. With annotations covering safety, the main residual gap is auth availability for historical versions, which is only hinted at via 'API-accessible'.

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 meaningfully disambiguates historyVersion as a project-history version rather than an OT version and implies omitting it yields the current source, but it never explains the 24-hex projectId format or the version numbering/range.

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 ('download') and resource ('complete current source ZIP'), and covers both modes: current source or historical version. It implicitly distinguishes itself from download_file by specifying the whole project ZIP rather than a single file, though it never names that sibling.

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

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

The description implies when to use it — for a full project archive rather than an individual file — and flags that the historical path requires the version to be 'API-accessible'. It gives no explicit exclusion or named alternative for per-file downloads, so the agent has to infer the boundary with download_file/read_file.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, but the description adds valuable behavioral context beyond them: link collaborators may appear only in presence, invitedMembers is not a complete participant list, online connections are grouped by account, and unavailable presence is reported as unknown.

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 three sentences with the core read behavior front-loaded, followed by focused caveats about presence and invited-member completeness. Every sentence adds useful information without repetition.

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

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

For a simple one-parameter read tool with annotations covering safety, the description gives useful output and completeness semantics. It still omits projectId scoping and there is no output schema, but the core behavioral picture is largely 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%, and the only parameter, projectId, is never mentioned in the description. The parameter name is self-explanatory and the schema supplies a pattern, but the description does not compensate for the missing schema documentation or explain scoping semantics.

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

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

The description states a specific verb and resource: it reads explicitly invited members and current online users separately. It also clarifies the two datasets and their caveats, though it does not name sibling tools or explicitly differentiate itself from tools like get_session_status.

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

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

The opening 'Read...' implies the tool is for inspecting collaboration and presence, but there is no explicit when-to-use guidance, no exclusions, and no named alternative such as get_session_status. Usage is therefore only 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context by explaining that state=completed signals job completion and that result.status determines compilation success, which is useful 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?

Two sentences, front-loaded with what the tool returns and followed by a crucial clarification about state vs. result.status. No wasted words; every sentence adds value.

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

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

Given the tool's simplicity and the absence of an output schema, the description adequately explains what is returned. It covers the key behavioral distinction between job state and compilation result. The only gap is the lack of explanation for the jobId parameter, but overall it is complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, meaning no parameter-level descriptions exist. The schema provides type, format, and pattern for jobId, but the description does not mention jobId at all, nor does it explain where to obtain the job ID (e.g., from a compile_project response). With only one parameter, the name is somewhat self-explanatory, but the description fails to compensate for the lack of schema descriptions.

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 (Get) and resource (compilation job state, PDF/log artifact URIs, actual compile status), and distinguishes job state from result.status. However, it does not explicitly differentiate from sibling tools like compile_project or get_session_status, which would clarify its role further.

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 usage is implied: it retrieves the result of a compilation job. No explicit when-to-use or when-not-to-use guidance is provided, nor are alternative tools named. An agent can infer the context but is left to rely on the tool name and description alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds meaningful behavioral context beyond that: the returned payload differs by mode (file content differences with path, file-tree differences without). It does not describe output shape or size limits, but with annotations carrying the safety profile this is solid.

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, zero filler, with the core action front-loaded and the mode distinction immediately after. Every sentence adds information the agent needs.

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

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

For a read-only comparison tool with no output schema, the description covers the action, the two modes, and the input source. It leaves the shape and granularity of the returned diff implicit, which is a minor gap rather than a blocker.

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, and it does explain the most ambiguous parameter: path is optional and switching it changes what kind of diff is returned. 'Versions returned by list_history' also implies what from/to accept. projectId is left unstated, but its meaning is self-evident from the name and pattern.

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 ('Compare two project-history versions') and further splits the behavior into two modes based on the optional path argument. It points at list_history as the source of inputs, which separates it from the file-reading siblings, though it never explicitly contrasts itself with read_file or download_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?

'Use versions returned by list_history' gives a concrete prerequisite and the correct upstream tool. The with-path/without-path sentence tells the agent which mode to expect, but there is no explicit when-not guidance or statement about comparing versions across different projects.

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, openWorldHint=true, and destructiveHint=false, so safety behavior is covered. The description adds useful return context by saying it returns the live file tree and main document, but it does not explain freshness guarantees, size limits, or what "main document" means.

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

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

The description is a single front-loaded sentence with no filler. Every word contributes to identifying the resource being retrieved.

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

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

For a simple read tool with annotations and one required parameter, the description gives a reasonable high-level return shape. However, it omits parameter guidance and does not clarify the structure or scope of the returned file tree and main document, which matters because there is no output schema.

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

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

The schema has 0% description coverage for the single required projectId parameter, and the description does not mention the parameter at all. It therefore adds no meaning beyond the parameter name and its 24-character hex pattern in the schema.

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

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

The description states a specific verb and resource: "Get the live project file tree and main document." It is clear this is not listing projects or reading an individual file, though it does not explicitly name sibling tools or define what the "main document" is.

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

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

The description gives no guidance on when to use this tool versus siblings such as list_projects, download_project, or read_file. It only implies a retrieval context through the word "live" and does not mention prerequisites, exclusions, or alternatives.

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, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds useful context about returned review data, the effect of the path parameter, and that data is limited by server permissions.

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 three tight sentences with the core read operation front-loaded. Every sentence adds relevant scope, parameter behavior, or permission context without unnecessary repetition.

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

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

With no output schema and no schema parameter descriptions, the description still identifies the returned review entities and the key scoping behavior. It is nearly complete, though it omits details such as ordering, pagination, or explicit projectId semantics.

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. It explains the optional 'path' parameter well, including its scoping effect, but does not explicitly describe the required 'projectId' parameter or its format.

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

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

The description gives a specific verb ('Read') and concrete resources: project-wide comments, replies, resolution status, file/line anchors, and visible tracked changes. It clearly defines the review-content domain, though it does not explicitly distinguish itself from siblings such as get_collaboration or read_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?

Usage is implied by the purpose statement, and the description clarifies that 'path' limits the annotation scan to one text file while threads remain project-wide. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions.

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=true. The description adds meaningful behavioral context beyond annotations by stating 'Never returns cookie values,' which is important for privacy and security-sensitive sessions.

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 concise sentences with no wasted language. It front-loads the core action and follows with a critical privacy 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?

With no output schema, the description reasonably explains that the tool reports session status, cookie renewal, and keepalive schedule, while explicitly noting that cookie values are never returned. It does not fully describe the response shape, but it gives enough context for an agent to call the tool correctly.

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

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

The tool has zero parameters, so there are no parameter semantics to document. The baseline score of 4 applies because the description does not need to compensate for missing parameter details.

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: checking the saved browser session, plus cookie renewal and keepalive schedule. It is clear enough to distinguish from unrelated sibling tools like list_projects or read_file, though it does not explicitly define what 'status' fields are returned.

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

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

There is no explicit guidance on when to use this tool versus alternatives or when not to use it. The context implies checking session health, but an agent must infer the appropriate timing and conditions.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false. The description adds useful context that filtering is not applied and pagination uses a server cursor, but it omits return format, error behavior, and authentication considerations.

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 short, front-loaded, and largely free of waste. The phrase 'as before' is slightly ambiguous, but the overall structure is efficient.

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

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

With no output schema and no schema parameter descriptions, the description leaves important details unexplained: what history records are returned, what projectId scopes, and how the cursor affects pagination. It supplies only partial context for a two-parameter 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?

Schema description coverage is 0%, so the description must explain the two parameters. It vaguely references a server pagination cursor, but does not clearly map that to the 'before' parameter, and it says nothing about the required 'projectId' parameter or its 24-character hex pattern.

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 says it returns the history API response unchanged, which implies a history-listing tool, but it never explicitly states what is being listed or how it differs from get_history_diff or list_history_labels. The lack of a clear verb+resource pairing leaves the purpose somewhat vague.

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 notes that no local time-window or subscription filtering is applied and mentions passing a server pagination cursor, but it does not say when to use this tool versus the sibling history tools. There are no explicit alternatives or exclusions.

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 establish read-only, open-world, and non-destructive behavior. The description adds useful context about session visibility and local plan restrictions, but it does not explain authentication needs, return shape, or pagination 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?

The description is a single front-loaded sentence with no filler. The scope details follow immediately and every phrase contributes to the tool's purpose.

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 is simple and the annotations cover its safety profile, but with no output schema the description should ideally say more about the returned label structure. It also leaves the required projectId parameter entirely to the schema.

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

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

There is one required parameter, projectId, and schema description coverage is 0%. The description never mentions projectId or explains its format, so the schema alone carries the parameter meaning; this is somewhat mitigated by the single obvious parameter 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 gives a specific verb and resource: 'Return project version labels,' scoped by session visibility and absence of local plan restrictions. It is clearly not a generic history call, but it does not explicitly distinguish itself from siblings such as list_history or get_history_diff.

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 states what the tool returns but gives no explicit guidance on when to use it instead of alternatives. 'Visible to the current session' and 'without local plan restrictions' are behavioral scoping details, not usage instructions or exclusions.

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=true, so the safety profile is covered. The description adds only the account-scoping detail; it says nothing about pagination, ordering, or whether results may be empty for accounts with no projects. The trailing phrase "using the server response" is opaque rather than informative.

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 that identifies the operation and its scope with no filler. The only weak element is the trailing "using the server response," which adds no actionable meaning.

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 read tool with a full annotation set, the description is nearly sufficient, but it leaves the agent guessing about the shape of the result (what fields a project entry has) with no output schema to fall back on. A brief note on the returned data would close that gap.

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 and the schema is trivially complete, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-parameter tool.

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 projects") plus a scope qualifier ("accessible to the signed-in account"), which is enough for an agent to distinguish it from get_project. It does not explicitly contrast itself with the single-project sibling, but the list-vs-get distinction is clear from the verb.

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: an agent can infer this is the tool for enumerating projects before calling get_project on one. There is no explicit when-to-use statement, no mention of prerequisites (auth scope) and no exclusion of alternatives.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond them: each call returns a fresh snapshot plus a version identifier and bypasses disk caches, which tells the agent results are always current. It stops short of describing error behavior or what happens at end-of-file.

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, front-loaded with the action and immediately followed by the freshness guarantee and the range option. No filler, no repetition of the name.

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

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

For a read-only tool with annotations and no output schema, the description covers what is returned (file text plus a fresh version) and how to narrow output via line range. Gaps remain around projectId identity and error/truncation behavior, but nothing critical blocks a correct call.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it only covers part of it: it clarifies that startLine/endLine form a 1-based optional range. Nothing is said about projectId (a 24-hex ObjectId), path semantics, or what happens if only startLine is supplied. Three of four parameters remain unexplained by either source.

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?

"Read a text file" names a specific verb and resource, and the qualifier "directly from the live document server ... not a ZIP or disk cache" distinguishes it from the download_* siblings in the same toolset. An agent can tell this apart from download_file/download_project 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?

The ZIP/cache contrast implies when this tool is preferred over bulk download, but the description never names an alternative or states an explicit use/avoid condition. Usage is inferable rather than stated, so it lands at minimum-viable guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the description's added value is the mutation semantics: single-occurrence replacement, content preservation, a version-freshness requirement, and the distinction between 'confirmed application' and 'final-content verification'. It could go further by stating what happens on zero or multiple matches and on version conflict, but it adds substantive context beyond the annotations and contradicts nothing.

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

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

Three sentences, front-loaded with the action and its key constraint, with no wasted prose. The final sentence about application versus content verification is slightly opaque in wording but conveys a meaningful behavioral distinction.

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

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

For a destructive, six-parameter mutation tool with no output schema, the description covers concurrency expectations and result semantics reasonably well, but omits failure behavior (unmatched or ambiguous oldText, version mismatch), and leaves half the parameters unexplained. Adequate but with clear gaps an agent would want filled before invoking.

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

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

Schema description coverage is 0% across six required parameters, so the description must carry the burden and does not. It only implies semantics for oldText ('exactly one occurrence'), path ('in a file'), and expectedDocId/expectedVersion ('recent'); projectId and newText are entirely undocumented, and no format or constraint details are added.

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

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

States a specific verb and resource with a scope constraint that distinguishes it from a general overwrite: 'Replace exactly one occurrence of oldText in a file, preserving surrounding content.' It does not name or contrast any sibling tool such as write_file or create_file, so an agent must infer where the boundary lies.

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 a real precondition ('Requires a recent document ID and version'), implying the tool participates in optimistic-concurrency control, which is genuinely useful for choosing it. However, there is no explicit guidance on when to use this versus write_file/create_file, nor on when not to use it.

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

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

The description says the tool stops a watch, which is a state-changing cancellation operation, while the annotations declare readOnlyHint=true. Although the added note about independent subscriptions and pending waits remaining active is useful, the core action conflicts with the read-only annotation.

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

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

The description is two short sentences and front-loads the main action. Every sentence contributes useful information without waste.

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

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

For a simple one-parameter cancellation tool with no output schema, the description covers the main behavior and clarifies what remains active. It omits idempotency and invalid-watchId behavior, which keeps it from being fully complete.

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

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

There is one required parameter, watchId, with 0% schema description coverage. The description implies that watchId identifies a watch created by watch_file, but it does not explain the required format or error behavior; the schema pattern supplies some format detail.

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, "Stop," and names the exact resource, "a watch created by watch_file." This clearly distinguishes the tool from watch_file and implies its role among the watch-related siblings.

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

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

The description gives clear usage context: use this to stop a watch that was created by watch_file. It does not explicitly state when not to use it or name alternatives such as wait_for_file_change, so it falls short of a 5.

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

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

Adds substantial behavior beyond the annotations: overwrite=true is the only path that permits replacement, the response separates acceptance, actual location, and content verification, and an unverified/unknown result must be inspected before retrying. This is consistent with destructiveHint=true and idempotentHint=false.

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

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

Front-loads the core action and constraints, then covers overwrite semantics, return behavior, retry guidance, and the ZIP edge case. Every sentence adds operational value with no filler.

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

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

For a destructive, non-idempotent mutation tool with no output schema, the description explains the dangerous parameter, the meaning of the return result, and how to handle uncertain outcomes. Combined with annotations and the input schema, an agent has what it needs to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the burden and mostly succeeds: it explains localPath as an absolute server-side path, path as project-relative with a basename default, and overwrite's default and destructive effect. projectId is only implied by 'existing project folder' rather than explicitly described.

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 ('Upload one local file') and scopes it to an existing project folder. The ZIP clarification further distinguishes this from project-import behavior, so an agent can separate it from siblings like write_file or create_file 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 clear operational context: localPath must be absolute on the MCP server, path defaults to the basename, and overwrite defaults to false. It also includes an important exclusion ('ZIPs are uploaded as files, not imported as projects'), though it does not explicitly name sibling alternatives such as write_file.

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

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

Adds real context beyond the readOnly/openWorld annotations: a hard 30-second cap, timeout semantics returning changed:false, and explicit reporting of disconnections. It stops short of covering rate limits or whether repeated waits are expected, but the safety profile is already carried by 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?

Three short sentences, front-loaded with what the tool does and the timeout bound, followed by return and error behavior. No wasted words.

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

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

With no output schema, the description usefully explains the return contract (new content vs changed:false vs disconnection). What remains missing is guidance on sourcing the version/id inputs and how this relates to watch_file, which matters for a 5-parameter tool.

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

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

Schema coverage is only 20% — only afterDocId carries a description. The description's mention of 'document version' hints at afterVersion and 'up to 30 seconds' hints at timeoutSeconds, but projectId, path, and the expected value of afterVersion (e.g. version from a prior read) are left unexplained, so the gap is not compensated.

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

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

Specific verb and resource: wait for a document version change, with a stated 30-second bound. It does not, however, distinguish itself from sibling tools like watch_file or read_file, so an agent must infer the difference.

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 a long-poll use case (wait for change up to 30s, get new content or changed:false), which signals when it fits. But it never names an alternative (e.g. watch_file vs this blocking wait) or states when not to use it.

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

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

The annotations already establish readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable push-semantics context ('server-pushed document changes') and discloses that a resource URI is returned, but it omits lifecycle details such as whether the watch persists until unwatch_file is called, whether it consumes resources, or what permissions are required.

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 with zero filler, and the primary action is front-loaded. Every sentence contributes to purpose or next-step behavior.

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 watch tool with no output schema and two required parameters that are entirely undocumented in the schema, the description should explain the returned resource URI more concretely and clarify watch lifecycle or cleanup expectations. It does a little but leaves significant gaps for an agent to call it correctly.

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

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

Schema description coverage is 0% for both required parameters (projectId, path), and the description does not mention either parameter or explain their meaning, format, or constraints. The definition provides no semantic help beyond what is already visible in the property 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?

The description uses a specific verb and resource: 'Start watching server-pushed document changes' clearly communicates the action and the change stream it produces. It does not fully distinguish itself from siblings such as read_file or unwatch_file, but the purpose is 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 names follow-up tools ('Use wait_for_file_change or subscribe to the returned resource URI'), which gives implied usage guidance without stating when to use watch_file instead of polling or reading the file directly. It does not mention when not to use it or how to stop watching.

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 destructive/non-idempotent/open-world, and the description adds real context beyond them: server-side verification of document identity and content, stale-version rejection, concurrent edits possibly merged by Overleaf, and the crucial recovery rule that an unknown write outcome blocks further writes on that connection until reconnect and inspection. This is exactly the failure-mode disclosure a write tool needs.

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

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

Front-loaded with the operation, then prerequisites, then failure behavior, then concurrency caveat; five tight sentences with no filler. Every clause carries operational content.

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

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

For a destructive, non-idempotent write with no output schema, the description covers preconditions, verification, and the blocked-connection recovery path, so an agent can call it safely. The remaining gap is what exactly `content` and `path` mean for a document that already exists.

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 parameter meaning and it only partly does. It explains `expectedDocId`/`expectedVersion` indirectly ('docId/version from a recent read') but says nothing about `projectId`, `path`, or what `content` represents (full body versus replacement text), leaving the most consequential field ambiguous.

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

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

States a specific verb and resource ('Replace text using OT edits') plus the mechanism (operational-transform edits preserving unchanged regions), which is far more than a restatement of the name. It does not draw the boundary against the sibling tool `replace_text`, so an agent cannot tell from the description alone which of the two to use.

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

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

Gives a clear precondition ('Requires docId/version from a recent read') and a failure rule ('Rejects stale versions'), which tells the agent when this call will succeed. It never names the alternative siblings (`replace_text`, `create_file`, `upload_file`) or says when file content should be written versus patched.

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