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

With no annotations provided, the description carries the full burden. It discloses the permanent, mutating nature, the clearing of pending-change metadata, automatic grouping across docs, and irreversibility—excellent transparency for a mutation tool.

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

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

Five short sentences, each providing essential information. Front-loaded with the core action, no redundancy, and well-structured for quick comprehension.

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 single-parameter tool with no output schema, the description covers purpose, effect, input sourcing, grouping behavior, and irreversibility. It is complete given the context and tool complexity.

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

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

Schema coverage is 100% and the schema description already references list_tracked_changes. The tool description repeats the source but adds no new parameter-level details, so baseline 3 is appropriate.

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

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

The description clearly states it permanently accepts tracked-change suggestions, and explains the effect on text and metadata. This distinguishes it from reject_changes by specifying what 'accept' means (text stays, metadata cleared).

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 clear context: use change_ids from list_tracked_changes and warns that the action is irreversible. However, it does not explicitly mention when to use this tool versus reject_changes, though the name and behavior imply the distinction.

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

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

With no annotations, the description carries the full burden. It discloses that it fetches output.log, parses error/warning counts, returns timings, and importantly notes that Overleaf returns 'success' even when LaTeX has errors, providing a truthful check. This goes beyond basic expectations and covers key behavioral nuances.

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 long, with the main action front-loaded. Every sentence adds value: the trigger and summary, the critical caveat about status, and the pointer to read_log. No fluff.

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?

Despite having no output schema, the description explicitly lists what the return contains (status, PDF produced, error_count, warning_count, first error lines, output file list, timings), making the tool's behavior fully comprehensible. The parameter schema is also rich, so the overall context is complete.

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

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

Schema coverage is 100%, so the description doesn't need to explain parameters. It does not add extra semantics beyond what the schema already provides for draft, root_doc, and stop_on_first_error, but that's acceptable given the high baseline.

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 triggers a LaTeX compile on Overleaf's CLSI and returns a unified summary. It specifies the exact action, target resource, and output fields, distinguishing it from sibling tools like read_log.

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 explains when to use this tool (to compile and get a summary) and when to use an alternative ('Use read_log for the full log when more context is needed'). It also clarifies the edge case of 'success' status to guide correct interpretation.

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

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

With no annotations, the description carries the transparency burden. It discloses that edits are applied as OT operations in real-time, that tracking is the default, and that only text docs are editable. It does not mention potential server-side overrides of the tracking request or stale-version races, though these are covered in the schema's parameter descriptions. Overall it provides meaningful behavioral context beyond a simple 'edit' summary.

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, front-loaded with the core action, and every sentence adds information: the mechanism, the default tracking behavior, the path default, and the file-type restriction. No redundant or filler 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 tool with no output schema and five parameters, the description covers the core purpose, typical usage, and key constraints. It does not explain the overridable tracking behavior or version-check parameters, but those are thoroughly described in the schema, so the description is sufficient to give the agent a solid mental model. The lack of authentication/permission details is acceptable as it is likely handled at a higher level.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the path default and the track behavior ('By default appears as a pending suggestion... pass track:'off' to write directly') and by stating the file-type restriction, which is not in the schema. However, it does not elaborate on strict_version or expected_version, which are already well-documented 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 clearly states the tool's function: 'Replaces the contents of a doc' via a minimal diff and OT operation over Socket.IO. It distinguishes from siblings by specifying the real-time nature, Review panel behavior, and the restriction to text documents. The purpose 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 description gives clear usage context: when to use track:'on' vs 'off', the default path behavior, and that binary files are not editable. However, it does not explicitly contrast with the sibling tool find_and_replace, which might be used for targeted substitutions rather than full-content replacement. The parameter descriptions in the schema add further mode guidance (auto/on/off).

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

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

With no annotations, the description discloses key behaviors: track:'on' default lands as pending suggestion, uniqueness requirement, ambiguity handling, OT operation minimalism, path default, race windows, cache-sync, and version checking. It also notes that track is a request not a guarantee (via schema, but description references).

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

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

The description is front-loaded with a clear summary, then structured into 'USE WHEN' and 'AVOID FOR BATCH WORK' sections. Every sentence adds value—no fluff. Length is justified by the tool's complexity.

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 tool with no output schema and no annotations, the description covers purpose, usage, edge cases, and trade-offs thoroughly. It does not enumerate response fields, but it provides sufficient context for an agent to decide when and how to invoke it. Minor gap: no explicit mention of success response structure, but the provided detail is strong overall.

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 covers all 7 parameters with detailed descriptions (100% coverage). The description adds some behavioral nuance (e.g., ambiguity resolution) but largely restates schema semantics. Baseline 3 is appropriate.

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

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

The description opens with a precise definition: 'Replace one occurrence — or all, with replace_all: true — of old_string with new_string in a doc, without re-emitting the rest of the file.' It clearly differentiates from edit_file by positioning itself as the surgical single-edit tool, and explicitly contrasts with edit_file in the usage guidance.

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 'USE WHEN' and 'AVOID FOR BATCH WORK' sections. It names edit_file as the alternative for batch work and explains trade-offs (round-trips, race windows, tracked-change entries).

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 annotation readOnlyHint=true aligns with 'Returns.' The description adds sorting and field details. However, it says 'Returns all review-panel comment threads' while the schema's include_resolved parameter defaults to false, meaning only open threads are returned by default, overstating the tool's behavior and missing a key default filter.

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, with the first sentence stating purpose and sorting, and the second enumerating returned fields and pointing to an alternative. No filler or redundant 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?

Without an output schema, the description provides a useful field list. It also gives context about the open project and points to the full-content tool. The gap is the 'all' vs. default-open-threads mismatch, but the schema's include_resolved description partially covers this. Overall quite complete for a read-only list operation.

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

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

Schema coverage is 100% with descriptions for all three parameters, so the baseline is 3. The description does not add significant parameter-level meaning beyond the schema; it mentions 'latest message preview' but does not explicitly connect it to the `full` parameter.

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

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

The description uses a specific verb ('Returns') and identifies the resource ('review-panel comment threads') and scope ('in the open project'), with sorting behavior. It also distinguishes from the sibling 'read_comment_thread' by pointing to it for full content.

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

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

It explicitly states 'Use read_comment_thread for full content,' providing a clear alternative. This makes it clear when to use the listing tool versus the full-content tool, offering strong 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 readOnlyHint and idempotentHint. The description adds valuable context that the tool uses cached data from open_project and makes no network calls, indicating potential staleness and a prerequisite that open_project must have been called. It also details the return entity structure, going beyond annotation coverage.

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 exceptionally concise, consisting of two information-dense sentences. It front-loads the core purpose and then adds relevant details about cost, data source, and return format, with no wasteful wording.

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 compensates by specifying the return structure (flat list, path, id, kind) and providing an example path. It also conveys the cheap/no-network nature, which is important for an agent's decision-making. The tool is simple with optional parameters, and the description is complete 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 100%, with both parameters (kind and path_contains) fully described including enum values and substring filter behavior. The description does not add significant parameter-specific details beyond what the schema already provides, so the baseline 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 states the tool returns the file tree of the currently open project as a flat list of project-relative paths. It specifies the resource (files) and the verb (returns/list), and is distinct from sibling tools like read_file (reads content) or list_projects (lists projects).

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

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

The description provides clear context by noting the tool is cheap and uses cached data from open_project, implying it is suitable for quick file tree lookups. However, it does not explicitly mention alternatives or when not to use it, lacking explicit exclusionary 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 readOnlyHint and idempotentHint, so the bar is lower. The description adds context by stating the sort order and the fields returned (id, name, last update time, owner), though it does not disclose pagination or error 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 two sentences, front-loads the action ('Lists projects'), and provides return value and usage guidance without any 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?

Given the simple read-only list operation, full schema coverage, and annotations, the description adequately covers return values and next-step usage. It is complete enough for an agent to select and 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?

All four parameters have schema descriptions with 100% coverage, so the baseline is 3. The description does not add parameter-specific meaning beyond what the schema already provides; it merely mentions sort order which is also 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 clearly states it lists projects on the configured Overleaf account with a specific verb and resource. It distinguishes from sibling tools like list_files by being the top-level project listing, and mentions sorting by most recent update.

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

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

It explicitly instructs to use the returned id with open_project for starting work, providing a clear workflow. However, it does not enumerate when not to use this tool or explicitly mention alternatives beyond open_project.

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 declare readOnlyHint=true, and the description adds behavioral scope: 'every pending tracked-change suggestion,' 'across all docs,' and the stability of change_id. It also clarifies it does not include comments, which is a behavioral boundary. This goes beyond the annotation without contradicting it.

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: first states purpose and key outputs, second explains workflow, third draws boundary with list_comments. Front-loaded with the action, no redundant 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?

Despite no output schema, the description enumerates the returned fields (author, doc path, op kind, position, text, change_id) and the new filter params are implied by the workflow sentence. It covers the tool's role in the change-acceptance process thoroughly given its moderate complexity.

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?

Input schema covers all 7 parameters with descriptions (100% coverage), so baseline is 3. The description adds workflow semantics by advising to 'filter the result by author / doc / kind / text' and collect change_id values, linking these filters to downstream accept_changes/reject_changes calls. This adds value beyond schema's individual parameter 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?

The description uses 'Enumerates every pending tracked-change suggestion' with a specific verb and resource scope ('across all docs'), and explicitly distinguishes from list_comments by stating 'Tracked changes only — review-panel comments are listed by list_comments.' This makes the tool's unique 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?

It provides explicit usage guidance: 'Use this to plan an accept_changes or reject_changes call' and tells the agent to filter and collect change_id values. It also names an alternative (list_comments) for comments, setting a clear when-to-use boundary.

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

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

With no annotations, the description carries the full burden. It discloses two notable side effects: joining a real-time Socket.IO session and caching the file tree. It also reveals the auto-close behavior when switching projects, providing valuable behavioral context beyond the basic action.

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

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

Two sentences, both purposeful and front-loaded. The first states the core action and side effects, the second gives the usage prerequisite and session behavior. No fluff or 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 single-parameter setup tool with no output schema and no annotations, the description fully covers purpose, required ordering, and session lifecycle. It gives an agent everything needed to know when and how 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 100% for the single parameter project_id, which includes a type, minimum length, and an example. The description adds no further parameter-level detail, so 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 uses a specific verb 'Joins' and names the resource 'the project's real-time Socket.IO session' while also stating it caches the file tree. This clearly distinguishes it from sibling file operations (list_files, read_file, edit_file) by framing it as an initialization step.

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

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

Explicitly states 'Must be called before list_files / read_file / edit_file' and notes that switching projects closes the previous session. This gives unambiguous when-to-use guidance and a clear sequencing rule relative to 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 description adds important behavioral context beyond the readOnlyHint and idempotentHint annotations: it explicitly clarifies that the tool does not contact Overleaf, which is a non-obvious and crucial trait for a health check. It also discloses the return value ('pong' and server version), enriching the behavioral picture.

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 consists of three short, front-loaded sentences: purpose, output, and a key caveat. Every sentence earns its place with no redundancy or filler, achieving maximum clarity in minimal 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 tool with zero parameters and no output schema, the description fully covers the necessary context: what it does, what it returns, and its critical non-contact behavior. The description is self-sufficient and leaves no significant gaps.

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

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

The tool has zero parameters, and the baseline for no parameters is 4. The description does not need to explain parameters, and it correctly doesn't mention any, keeping the focus on behavior and output.

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 tool as a health check and specifies the exact output: 'pong' and the server version. It is distinct from all sibling tools, none of which serve as a health check, and uses a specific verb ('Health check') plus resource.

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 that the tool 'does not contact Overleaf', which is an explicit when-not statement, indicating this is a safe local call without side effects. However, it does not explicitly name alternative tools or provide broader usage context, so it stops short of full usage guidelines.

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 readOnlyHint annotation already declares this as a read operation. The description adds valuable context beyond the annotation by detailing the returned content (full message history with authors and timestamps), which is especially useful given no output schema. No contradiction 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 two concise sentences with no unnecessary fluff. It front-loads the core function and then provides a usage tip, making every sentence earn its place.

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

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

For a simple read-only tool with one parameter, the description covers the function, the return contents, and the trigger condition for use. It does not mention error handling or edge cases, but these are not essential for this straightforward operation given the annotations.

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

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

The schema fully describes the single parameter thread_id with a clear explanation. The description reinforces the source of the ID (from list_comments) but does not add substantial semantic value beyond the schema, so the baseline 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 states the tool fetches the full message history of one thread, specifying the resource and scope ('all replies with author + timestamp'). It also distinguishes itself from the sibling list_comments tool by indicating this is for reading a specific thread after discovery.

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 says 'Use this when `list_comments` shows a thread that looks relevant', providing a clear when-to-use scenario. It does not explicitly name alternatives or exclusion conditions, but the context of sibling tools implies the distinction.

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 goes beyond the readOnlyHint annotation by detailing output structure: full text in content and structuredContent.text for text files, base64 and MIME type for binaries, and metadata (version, counts, ranges). This gives the agent a clear picture of what to expect, despite not covering error cases.

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

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

Two sentences, front-loaded with the action, then structured details about output formats. No filler words; every phrase adds information.

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

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

Given there is no output schema, the description fully inventories the response structure (content, structuredContent, metadata, MIME type) and covers both file types. It also mentions the default path behavior, making the tool self-contained enough for an agent to use 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 sole parameter 'path' is fully described in the schema, and the description adds the default value (root doc) and references open_project's response for discovering it. This is valuable context 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 uses the specific verb 'Reads' and identifies the resource as 'a file by project-relative path', distinguishing it from sibling tools like list_files (which lists) and edit_file (which modifies). It also clarifies the handling of text vs binary files, making the tool's 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 implies when to use this tool (when file contents are needed) and notes the default behavior when path is omitted, referencing open_project's response. However, it does not explicitly contrast with alternatives (e.g., 'use list_files to see available files'), so it stops short of full differentiation.

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 discloses detailed behavioral traits: the `content` array shows a summary of `!`-prefixed error lines at the top, and the log is truncated to the last 8000 chars for display, while `structuredContent.log` contains the full untruncated log. This goes beyond the readOnlyHint annotation and explains exactly what callers can expect.

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, each earning its place: the first states the core purpose, the second provides usage guidance, and the third details the response format. It is front-loaded and free of 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?

Given the tool has no parameters and no output schema, the description fully compensates by explaining both the display content and the full structured content. It addresses how the tool differs from `compile` and what the caller can parse. This is complete for a zero-parameter, read-only logging 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?

The tool has zero parameters, and the schema coverage is 100% as there are no properties. The description does not need to explain parameter semantics, but it enriches understanding by explaining the response structure. Baseline for zero parameters is 4, and this description meets that.

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

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

The description clearly states the tool returns the full LaTeX log from the most recent compile call, with a specific verb ('Returns') and resource ('full LaTeX log'). It distinguishes itself from the sibling `compile` tool by noting that `compile` already provides error count and first few errors, making this tool's purpose clear and complementary.

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 states when to use this tool: 'use this only when you need more context (full log, line numbers, package warnings, etc.)' and contrasts it with `compile`, which includes error count and first few errors. This provides clear usage guidance and indirectly names an alternative.

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

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

With no annotations, the description carries the full burden. It discloses that the operation is irreversible, explains the distinct handling of inserts and deletes, and even mentions the underlying OT implementation (u:true flags) and Overleaf parity. This is strong transparency, though it omits error scenarios or invalid id 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?

Three sentences, all information-dense and front-loaded with the primary purpose. Every sentence earns its place: action/effect, implementation detail, and source of ids with an irreversibility warning. No word 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?

The tool is a simple mutation with one parameter, and the description covers the core behavior, data source, and irreversibility. The absence of error-handling details or return format is acceptable given no output schema and the straightforward nature, but it could be slightly more complete with invalid-id behavior.

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

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

The schema covers 100% of parameters, providing a description for change_ids. The tool description adds value by explicitly telling the agent to source change_ids from list_tracked_changes, and clarifies the param refers to tracked-change suggestions. It also implicitly corrects the schema's 'to accept' wording by using 'rejects'.

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 'Rejects the specified tracked-change suggestions', using a specific verb and resource that clearly identifies the action. It further distinguishes itself from the sibling accept_changes by detailing the exact outcome for inserts vs deletes. This is unambiguous and contextually differentiated.

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 instruction to 'Pass the `change_id` values from `list_tracked_changes`' provides clear guidance on where to obtain the required input. While it doesn't explicitly state when to avoid using it, the inverse nature versus accept_changes is inherent in the description, and the irreversibility warning implies caution.

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

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

No annotations are provided, so the description carries full burden. It simply restates the action without explaining side effects, required permissions, or what 'reopen' entails (e.g., whether the thread becomes editable again, if replies are allowed).

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 sentence with no redundant words or repeated information. It is appropriately minimal for a simple tool with one parameter.

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

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

This is a simple one-parameter tool with a clear name and no output schema. The description covers the core purpose, but the lack of annotations and behavioral details means it does not fully explain the consequences of the action. It is adequate but leaves room for more 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 100% for the single parameter thread_id, which is fully described with an example source ('e.g., from list_comments'). The description adds no additional meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description 'Reopens a previously-resolved thread' clearly states the specific verb (reopens) and resource (thread). It distinguishes itself from the sibling tool 'resolve_comment' by indicating the opposite 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?

No explicit guidance on when to use this tool versus alternatives. The context of sibling tools like 'resolve_comment' and 'list_comments' implicitly suggests a use case, but the description provides no when/when-not criteria or alternative recommendations.

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

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

With no annotations provided, the description carries the full burden of disclosure. It clearly indicates this is a write operation by stating it 'adds a new message' and gives a concrete behavioral effect: 'appears immediately in Overleaf's review panel for collaborators.' This goes beyond the schema, though it omits potential side effects like notifications or error conditions.

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

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

The description is concise, composed of three short sentences, each adding essential information: the core action, how to obtain thread IDs, and the immediate visibility effect. 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?

For a simple two-parameter tool with no output schema, the description covers the key aspects: what it does, where thread_ids come from, and the result of the action. It omits any prerequisites (e.g., project ownership, open project) but given the straightforward scope, it is sufficiently complete.

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

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

Schema description coverage is 100% for both parameters, with thread_id already referencing list_comments. The description's separate mention of list_comments adds no new parameter meaning beyond what the schema provides, so the baseline 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 states the action ('Adds a new message') and the target resource ('existing comment thread'), which immediately distinguishes it from siblings like resolve_comment or reopen_comment. The title reinforces this, and the mention that threads come from list_comments further anchors its purpose.

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 the correct usage workflow: first obtain a thread via list_comments, then use this tool with the thread_id. It provides clear context for when to use this tool, though it does not explicitly state when not to use it or name alternative tools for different actions (e.g., resolving).

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('marks as resolved') but does not mention potential side effects, whether the action is reversible (though a sibling reopen_comment exists), or any permissions/constraints. This is a gap for a mutation tool.

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

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

Two sentences, front-loaded with the action, followed by a concise usage guideline. No redundancy or 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?

The tool is simple with a single parameter and no output schema, and the description covers purpose and usage. However, the lack of behavioral details and annotations means the description is only minimally complete, not fully transparent about consequences.

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

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

Schema coverage is 100% (thread_id is documented with an example source). The description adds no parameter-specific information beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Marks') and resource ('a thread as resolved'), clearly distinguishing it from sibling tools like reply_comment and reopen_comment. It also adds context on when this action is appropriate.

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 clear context on when to use the tool ('after addressing the comment'), with a concrete example. It doesn't explicitly state when not to use it or mention alternatives, but the guidance is sufficient for a simple operation.

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