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 behavioral burden. It discloses that the tool does not alter document text, requires a specific version source, and rejects stale versions. It does not cover all possible side effects or failure modes, but it gives meaningful behavioral transparency.

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, each carrying essential information. There is no fluff, and the most important constraints are front-loaded.

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

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

For a low-complexity tool with no output schema and no annotations, the description covers the key operational constraints: anchoring, uniqueness, version sourcing, and non-mutation. It does not describe return values, but for a simple create operation this is a minor 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?

Schema description coverage is 0%, so the description must compensate. It adds meaning for expected_version ('must come from read_file') and selected_text ('unique'), but path and content are left entirely to the schema. This is partial, not complete, semantic coverage.

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 ('Create'), a specific resource ('native anchored comment'), and a clear target ('unique selected text'). It also distinguishes this tool from siblings like reply_comment and resolve_comment by emphasizing that it does not change document text.

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 a clear prerequisite: expected_version must come from read_file, and it warns that stale versions will be refused. It does not explicitly name alternatives or say when not to use it, but the usage context is clear enough.

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

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

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 destructiveHint false, the annotations already communicate that this is a non-destructive operation. The description adds the 'empty text document' nuance, but it does not disclose behavior such as what happens if the path already exists, whether content is overwritten, or whether an error is returned. A 3 is appropriate because the safety profile is already annotated but some behavioral context is still missing.

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 filler. The core action is front-loaded, and the sibling-tool routing is stated efficiently in the second sentence.

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 low-complexity tool with one required parameter, no output schema, and a safety annotation. The description explains what the tool does and routes to edit_file when content insertion is needed. The main omission is a note about overwrite or existing-file behavior, but the tool is simple enough that the description is nearly 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?

The schema has 0% description coverage for the only parameter, 'path', and the description does not explain the parameter's meaning, format, or constraints beyond the schema's type and minLength. For low schema coverage, the description should compensate, but it does not provide any parameter-specific guidance.

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: 'Create an empty text document.' It also distinguishes the tool from the sibling edit_file by noting the intended difference ('Use edit_file for tracked content insertion'), so an agent can tell them apart without inspecting 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?

The description explicitly names an alternative tool and the condition under which that alternative should be used: 'Use edit_file for tracked content insertion.' This gives clear, direct when-to-use versus when-not-to-use guidance.

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

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

The annotation only includes destructiveHint=false, so the description rightly implies a non-destructive creation operation. It adds context about the prerequisite (parent must exist), which is useful. However, it does not explain potential errors (e.g., what happens if parent doesn't exist) or other side effects, but given the low complexity, this is acceptable.

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 extremely concise, two short sentences, with no filler. It front-loads the core action and adds the critical constraint. Every word is meaningful, and it is appropriately brief for such a simple operation.

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

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

For a single-parameter tool with no output schema, the description is mostly complete: it states the action and the prerequisite. However, the path parameter is under-specified, which is a notable gap for an agent to correctly formulate the call. This could be improved by clarifying the expected path format.

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 is minimal: only one required string parameter 'path' with no description. The tool description does not elaborate on what the 'path' should represent (e.g., whether it's a full path or relative, whether it includes the folder name). With 0% schema coverage, the description should compensate, but it does not, leaving the agent to infer.

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

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

The description clearly states the tool's purpose: to create one folder in the open project, with the constraint that the parent must exist. It uses a specific verb ('create') and resource ('folder'), which is clear and distinct from file creation tools.

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 tool should be used for creating folders in the active project, distinguishing it from file operations. It also gives a key condition ('Parent must exist'), which is essential for successful usage. However, it does not explicitly mention alternative tools (e.g., create_file) or 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?

Annotations already mark destructiveHint=true, but the description adds valuable context: the need for explicit confirmation and the refusal of recursive deletion. This goes beyond the annotation by explaining the safety mechanism and the boundary of what is 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?

Two sentences with zero filler. The action is front-loaded, and the safety constraint follows immediately. Every word earns its place.

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

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

For a simple two-parameter deletion tool, the description covers the essential behaviors: what it deletes, the confirmation requirement, and the recursive-deletion limitation. It doesn't discuss error handling or return values, but the absence of an output schema and the tool's simplicity make this acceptable.

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

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

The description explicitly mentions 'requires explicit confirmation', which explains the purpose of the 'confirm' parameter. However, it provides no detail about the 'path' parameter beyond 'file or folder' – no format, examples, or constraints beyond the schema's minLength. With schema coverage at 0%, the description partially compensates but doesn't fully clarify both parameters.

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

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

The description clearly states it deletes a file or folder, which is a specific verb and resource. It distinguishes itself from sibling tools like rename_entity, create_file, and upload_file by focusing exclusively on deletion.

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

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

The description gives practical usage constraints: it requires explicit confirmation (implying the 'confirm' parameter must be set to true) and refuses recursive folder deletion. While it doesn't name alternative tools explicitly, the deletion use case is self-evident and the constraints are clearly stated.

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

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

Annotations include destructiveHint=false, which covers safety profile. The description adds no further behavioral context — no mention of permissions, whether the file is a snapshot of current state, or any side effects. With sparse annotations, the description could explain what 'download' implies but does not.

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?

Single sentence, concise and front-loaded. However, it omits important details about tool behavior and alternatives, making it under-specified rather than efficiently concise. No wasted words, but also no substance beyond a basic statement.

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 download tool with no output schema and minimal annotations, the description is too brief. It does not clarify the distinction between this and sibling download tools, nor does it explain any caveats like 'snapshot' semantics or whether the file is binary/text. Insufficient for an agent to reliably choose this 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 50%; only output_path has a description. The description does not explain the 'path' parameter (what it refers to, format, or scope). The tool description adds no value beyond the schema for parameters, failing to compensate for the undocumented 'path'.

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 action ('Download') and resource ('document snapshot or binary file') from the 'open project'. It is clear but does not differentiate from sibling tools like download_project or download_output, which also involve downloading. Lacks specificity on what counts as a 'document snapshot'.

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

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

No guidance on when to use this tool versus alternatives such as download_project or download_output. No context on prerequisites, project state, or typical use cases. Leaves the agent to infer usage.

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

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

Annotations only include destructiveHint=false, which the description does not contradict. The description adds useful behavioral context: it defaults to output.pdf and the schema notes 'Never overwrites.' However, it doesn't disclose what happens if no compile has been run, whether the artifact is a file or directory, or any side effects. With minimal annotations, the description carries some burden but provides only partial transparency.

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, each earning its place: what it does, the precondition, and the default. Front-loaded with the action and resource.

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 download tool with one required parameter and no output schema, the description is mostly complete. Gaps: no mention of error behavior if compile hasn't run, no mention of whether the artifact name must match a file in the compile output, and no explicit alternative routing to download_file/download_project. Still, the core usage is clear.

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 50%: output_path is documented in the schema, artifact is not. The description adds meaning for artifact by stating the default 'output.pdf', which is helpful. It doesn't explain what artifact values are valid beyond the default, but the schema already covers output_path's 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 states a specific verb ('Download') and resource ('an artifact from the last compile'), and distinguishes it from sibling download tools by tying it to the compile step. It doesn't explicitly name sibling alternatives, but the context is clear enough.

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

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

It gives a clear precondition: 'Run compile first.' This tells the agent when the tool is valid. It doesn't explicitly say when to use download_output vs download_file or download_project, but the compile-specific context 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?

Annotations only provide destructiveHint: false, so the description carries much of the behavioral burden. The '(no extraction)' note adds functional context, and the schema's 'Never overwrites' is a behavioral trait, but that lives in the parameter schema rather than the description. Nothing discloses size limits, error behavior, or prerequisites, though the description adds a bit of value beyond 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?

A single sentence with zero filler: verb, resource, format, and a behavioral clarification. Every word earns its place, and the scoping information is front-loaded.

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

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

For a single-parameter tool with full schema coverage, the description covers the essentials. However, it fails to clarify when download_project is preferred over download_file or download_output, and it leaves the prerequisite of an open project implicit. A tool with three sibling download-oriented tools should address this routing 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?

Schema description coverage is 100% – the single parameter output_path is fully documented in the schema ('Absolute local output path; parent must exist. Never overwrites.'). The description adds no parameter-level meaning beyond the schema, so it meets the baseline of 3 without exceeding it.

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

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

The description 'Download the open project as a ZIP archive' states a specific verb (download), a resource (the open project), and the output format (ZIP). The parenthetical '(no extraction)' adds useful scope clarification. It is clear and distinct enough from download_file and download_output, though it doesn't explicitly differentiate itself from those sibling download tools.

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 no guidance on when to use this tool versus the sibling tools download_file or download_output. The only usage hint is 'the open project,' implying a required prior context (a project must be open), but no explicit prerequisites or exclusions are stated.

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

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

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?

The annotation only provides destructiveHint: true. The description adds a valuable behavioral detail by stating that existing targets are refused, meaning the tool will not overwrite an existing file or folder. It does not cover broader effects like broken references, but that is reasonable for a simple rename operation.

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

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

The description is a single, well-structured sentence that leads with the action and then includes two high-value constraints. Every word contributes meaning, with no redundant or vague 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 two-parameter tool with no nested objects and no output schema, the description covers the core operation and the most important edge case (refusing existing targets). It could mention success/error behavior or permissions, but the operation is simple enough that the current description is nearly complete.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It clarifies that `path` refers to an existing entity and that `new_name` is a new name within the same parent, but it does not specify exact formats, constraints, or whether extensions or path separators are allowed.

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 operation (rename), the resources (file or folder), and the constraint (within its current parent). It also adds a distinguishing behavior (refuses existing targets), which helps separate it from sibling tools like create_file, delete_entity, or edit_file.

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

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

The intended use case is implied: renaming an existing file or folder without moving it. However, it does not explicitly state when to prefer this tool over siblings, nor does it mention alternatives such as using create_file for new files or delete_entity for removals.

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.

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

Annotations only provide destructiveHint=false, so the description carries the burden of behavioral disclosure. It adds important context: the tool refuses existing targets and text files, and must not run concurrently with other tree changes. It doesn't detail failure modes or side effects, but the key behavioral constraints are disclosed.

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

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

Three sentences, each earning its place: the core purpose, the exclusions/alternatives, and the concurrency warning. Information is front-loaded and there is zero 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 two-parameter upload tool with no output schema, the description covers the essential context: what it accepts, what it refuses, and when not to run it. It could add parameter format details, but the core decision-making 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 description coverage is 0%, so the description must compensate. It names the two parameters implicitly (path and local_path) but doesn't explain their format or relationship beyond 'upload a NEW binary asset'. The description adds some meaning but leaves the agent to infer that path is the destination and local_path is the 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?

The description clearly states the tool uploads a NEW binary asset only, explicitly excluding existing targets and text files. It distinguishes itself from create_file and OT edits, making its 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 explicitly says when to use this tool (new binary assets) and when not to (existing targets, text files), and names alternatives (create_file and OT edits). It also warns against concurrent execution with other tree changes, providing clear usage context.

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