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

Annotations are minimal (readOnlyHint=false, etc.), so the description carries the burden. It discloses key behavioral traits: path resolution to repository root (preventing duplicate adds), name defaulting behavior, and failure condition (NOT_A_GIT_REPOSITORY). This goes beyond the annotations and is valuable for the agent.

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 (three sentences) and front-loaded with the core purpose. Each sentence adds essential detail: purpose, path behavior, and failure mode. No fluff or redundant phrasing.

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

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

The tool has simple inputs and no output schema, but the description covers all necessary aspects: how path is used, name defaulting, and error conditions. There is no missing information that an agent would need to invoke it correctly, given the 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?

Schema coverage is 0%, but the description thoroughly explains both parameters: `path` can be any directory inside the working tree and is resolved to root; `name` defaults to folder name. This adds meaning that the schema (only type and constraints) does not provide, fully compensating for the lack of schema descriptions.

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

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

The description clearly states the action (start tracking) and the resource (a git repository). It distinguishes itself from siblings like list_repositories and remove_repository by focusing on the 'add' action, and it provides specific details about path resolution that prevent ambiguity.

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 context on when to use: when you want to start tracking a git repository. It does not explicitly mention alternatives, but the sibling names (e.g., update_repository, remove_repository) imply different purposes. It provides a key exclusion: fails if not a git repository, which helps the agent decide when not to use.

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 far beyond the annotations. It details how anchors are resolved (a line not in the diff is looked up in the head file, only a line in neither is kept unanchored), that comments are attributed from the MCP handshake, that unattached paths are left as text rather than failing the call, image type/size limits, and the distinct guiUrl vs webUrl behaviors. It confirms the annotations (write, non-idempotent, non-destructive) without contradicting them - no contradiction.

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?

Core positioning semantics are front-loaded, which is good. But the description sprawls: three paragraphs are devoted to markdown image syntax, path-escaping with spaces, file formats, and size limits, and another two long paragraphs to tailnet/webUrl mechanics. Valuable detail, but much of it could be condensed; it does not earn every sentence's 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 an 8-parameter tool with no output schema and zero schema descriptions, the description covers the intricate comment-placement logic and even partial return-value fields (thread anchoring result, guiUrl, webUrl). The notable gap is two undocumented parameters - 'changes' and 'agentLabel' - which no structured field explains. Nearly complete, but those omissions keep it from a 5.

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

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

Schema description coverage is 0%, so the description must carry the explanatory load. It does this superbly for the hard parameters - filePath/line pairing, the 'side' head/base meaning, and startLine's block semantics. But it leaves several parameters unaddressed: the 'changes' enum (committed/all/uncommitted) is never explained, and 'agentLabel' is not mentioned at all. Strong compensation for the tricky location params, incomplete for the rest.

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

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

Opens with a specific verb-plus-resource: 'Start a new discussion on a review.' This cleanly stakes out its place against the sibling set (reply_to_review_comment, update_review_comment, delete_review_comment, resolve_review_comment) - it is the one that opens a fresh thread, not one that replies to, edits, or deletes an existing one. The title reinforces it without needing the schema.

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

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

The 'Start a new discussion' framing plus the description of line anchoring ('the way a pull-request review comment works') gives clear context for when this tool applies. However, it never explicitly names the sibling alternative or states an exclusion - e.g., it does not say 'for replies to an existing comment use reply_to_review_comment.' The when-to-use is strongly implied but the when-not-to-use alternative is left to inference.

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

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

Annotations already mark the tool as idempotent and non-destructive, and the description adds useful behavioral context: the tool name comes from the MCP handshake and cannot be changed, and the label persists until the server process exits. This is consistent with the annotations.

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

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

The description is two sentences with the primary action front-loaded, followed by essential constraints and one illustrative example. Every sentence adds necessary context without 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 tool with one optional parameter and no output schema, the description covers what the tool does, when to use it, and how the label behaves. A precise statement of the returned attribution fields would be marginally helpful, but the current description is sufficient for correct invocation.

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

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

The schema provides no description for the 'label' parameter (0% coverage), so the description must compensate. It does so by explaining that 'label' is a short session handle, giving an example ('auth-refactor'), and clarifying its persistence and use case.

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 ('Show') and a distinct resource ('how comments from this session will be attributed'), and also covers the optional 'set a label' behavior. This clearly distinguishes it from the CRUD repository/review/comment siblings.

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

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

The description gives clear context for when setting the label is worthwhile ('when more than one agent is working the same review') and notes the label's lifetime. It does not explicitly discuss when not to use the tool, but no sibling alternative exists, so the guidance is adequate.

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 indicate a non-read, non-idempotent, non-destructive operation. The description goes far beyond that: it specifies the INVALID_INPUT failure mode, inclusion of uncommitted changes, URL behavior across server states and restarts, and token/cookie exchange. This is exactly the kind of behavioral context an agent needs and is not in annotations.

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

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

The description is long but each sentence carries unique value. It is front-loaded with the core action and then layers ref semantics, output behavior, and URL usage. It could be trimmed slightly without losing meaning, but the structure is logical and not redundant.

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 explains the return values (guiUrl, webUrl) and their intended use, error handling, and edge cases (uncommitted work, same ref, server not running). This is complete for an agent to invoke the tool correctly and present results appropriately.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning. It thoroughly explains baseRef and headRef (including merge-base, uncommitted work, same-ref case) and the title default, and also covers description implicitly by allowing it. This fully compensates for the missing schema documentation.

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

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

The description opens with a clear, specific verb+resource: 'Open a review comparing two refs in a tracked repository.' It distinguishes this creation tool from sibling review tools (list, get, update, remove) by explaining the diff-from-merge-base semantics, so an agent can select it without ambiguity.

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 practical conditions for use (both refs must exist, title default, same-ref allowed for uncommitted work) and explains when to offer guiUrl vs webUrl based on user context. It doesn't explicitly contrast with alternatives, but the purpose is unambiguous and the guidance is rich enough for correct invocation.

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 carry destructiveHint=true and readOnlyHint=false, so the description adds value by disclosing the thread-cascade behavior and the self-authored-message restriction. These details are not available in the structured metadata and are essential for a destructive 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 two tight sentences with the primary action and the most consequential side effect front-loaded. There is no filler, repetition, or irrelevant detail.

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

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

For a one-parameter destructive tool, the description covers the core action, a key side effect, and the permission restriction, which is enough to invoke it safely. It does not specify behavior when a message has replies, but that level of detail is not clearly necessary for this simple tool.

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

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

Schema description coverage is 0%, and the description does not explain what `id` refers to or how to obtain it; the agent must infer that it is the comment/message ID. Because the schema provides no parameter description, the description should have compensated but did not.

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

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

The description leads with a clear verb-resource pair, 'Delete one message,' and the tool name/title specify that the target is a review comment. This distinguishes it from comment-related siblings like update_review_comment and resolve_review_comment.

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

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

The description provides a relevant permission constraint: an agent can only delete messages written by its own tool-twitter. However, it does not explicitly state when deletion should be chosen over alternatives like resolve_review_comment or update_review_comment; usage is mostly implied by the tool name.

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

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

Annotations already provide readOnlyHint=true, so the description correctly aligns with that. It adds the behavioral context that the response includes 'live git state', which informs the agent about the nature of the returned data. This goes beyond the annotation and adds value.

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, efficient sentence that front-loads the verb and resource. Every word adds meaning, with no redundancy or 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 simple fetch operation with one parameter and no output schema, the description is complete: it states what is fetched and that the result includes live git state. There is no missing information that an agent would need to call the tool correctly.

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

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

The schema has one parameter (id) with 0% description coverage. The description directly references 'by id', explaining that the id is the repository identifier. While it doesn't detail the type or constraints, the schema provides those, and the description clarifies the semantic purpose of the parameter, which compensates for the low 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 clearly states the action (fetch) and the resource (one tracked repository) with an id parameter. It also adds specificity by mentioning 'live git state', which distinguishes it from a simple metadata fetch. This differentiates it from sibling tools like list_repositories.

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

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

The description implies usage for fetching a single repository when you have its id, which is clear from the phrase 'by id'. However, it does not explicitly mention when to use this over alternatives or when not to use it, so it lacks explicit exclusions but provides clear context.

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 far beyond the annotations (readOnlyHint=true, openWorldHint=false) by detailing the behavior of the returned guiUrl and webUrl, including conditions under which each is present, the token exchange behavior, and the troubleshooting advice for when the link fails. This is significant behavioral context that an agent would need to correctly act on the result.

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

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

The description is long (~200 words) but each paragraph earns its place: the first sentence is the core function, the next explains the critical guiUrl behavior, and the last clarifies the webUrl alternative. The structure is logical and front-loaded with the essential action.

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

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

For a tool with one parameter and no output schema, the description covers the returned data (review plus repository), the two URLs and their use cases, the token behavior, and the troubleshooting path. There is nothing an agent needs to know to call the tool and present results correctly that is missing.

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

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

With schema coverage at 0%, the description must compensate. It does clarify that the 'id' parameter is the review identifier ('Fetch one review by id'), adding meaning beyond the bare integer type. However, it does not elaborate on the nature of the id (e.g., where it comes from) or any format expectations, so the addition is minimal.

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 a specific verb ('Fetch') and resource ('one review by id'), and distinguishes itself from the sibling list_reviews by specifying it returns a single review with its attached repository. This gives an agent an unambiguous understanding of what the tool does.

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

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

The usage is implied: use this tool when you have a review id and need the details. However, the description does not explicitly mention alternatives or provide exclusions, such as 'use list_reviews to browse all reviews.' The extensive guidance on how to present the returned links is more about output handling than about when to invoke the tool.

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

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

Annotations already declare readOnlyHint=true, but the description adds significant behavioral context: git state is read fresh on every call and never cached. It also details the specific state fields returned, which is useful for an agent. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core action, and every clause adds value. The description is efficient and well-structured.

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

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

For a zero-parameter list tool with readOnlyHint annotation, the description fully covers what the tool does, what each result contains, and the live/caching behavior. No output schema exists, but the description sufficiently communicates the return content. Nothing essential is missing.

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

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

The tool has zero parameters, so the description need not explain them. The baseline for zero parameters is 4, and the description adds no unnecessary parameter information, which 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 ('List') and resource ('every git repository tracked in GitWarren'), and enumerates exactly what is included (folder existence, repo status, current branch). This clearly distinguishes it from sibling tools like get_repository or add_repository.

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 it is for retrieving all repositories, and the sibling names make the distinction obvious. However, it does not explicitly state when to prefer this over get_repository or mention any exclusion criteria. It provides clear context but no explicit 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?

Annotations declare readOnlyHint=true and openWorldHint=false, so the safety profile is already known. The description adds substantial behavioral context: anchor semantics (anchored/moved/outdated), resolution of threads against head files rather than the patch, attachment URL behavior (internal token, not fetchable), guiUrl behavior across restarts and serve modes, and webUrl tailnet behavior. The only minor gap is that it doesn't explicitly state the return format or pagination, but the description is rich enough that this is a small omission.

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 information-dense and front-loaded with the core purpose, but it is quite long and covers a lot of edge-case behavior (tailnet, tokens, cookies, restart behavior) that could be trimmed or moved to a more structured format. Every sentence does earn its place in terms of unique information, but the length makes it harder to parse quickly. It is not bloated with repetition, but it is at the upper limit of what an agent can efficiently consume.

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

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

For a read-only list tool with one parameter and no output schema, the description is remarkably complete. It covers the full range of what an agent needs to know: what results contain, how to interpret anchors, how to handle attachments, how to present links, and how to troubleshoot link failures. The absence of an output schema makes the description's detailed explanation of result fields (anchor, anchorSnapshot, attachments, guiUrl, webUrl) essential, and it delivers.

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

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

Schema description coverage is 0%, so the description carries the full burden for the single parameter. The description doesn't explicitly explain reviewId, but the tool name and title ('List review comments') plus the opening sentence make it clear that reviewId identifies the review whose comments are listed. With only one parameter and a self-evident name, the description's implicit coverage is adequate, though it could have explicitly stated 'reviewId: the review to list comments for.'

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

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

The description opens with a clear statement of what the tool does: lists every discussion on a review, including review-level threads and line comments, with full message history and authorship. It distinguishes itself from sibling comment tools (add, reply, resolve, update, delete) by being the read/list operation, and from list_reviews by operating on comments within a review. The scope is specific and 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 provides extensive usage guidance: check the anchor before acting on a line comment, use anchorSnapshot for outdated comments, read the alt text before fetching attachments, show guiUrl to the user, offer webUrl when the user is not at this machine, and both when uncertain. It also explains when not to fetch attachment URLs and how to handle a link that won't open. This is explicit when-to-use and how-to-use guidance that goes far beyond a basic description.

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

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

Goes far beyond the readOnlyHint annotation by disclosing ordering, the ref-vs-commit interpretation, guiUrl behavior regardless of whether GitWarren is running, token/cookie behavior after restarts, and the tailnet conditions for webUrl. This gives the agent concrete expectations for results and failure modes. No contradiction with the annotations.

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

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

The main action and filtering are front-loaded and paragraphs separate core behavior from link guidance. However, the description is quite long for a two-optional-parameter list tool; the token/cookie troubleshooting and tailnet scenarios are detailed enough that not every sentence earns its place.

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

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

Even without an output schema, the description tells the agent what results contain (guiUrl, conditional webUrl), how to present them, and how the review object should be understood. It also covers edge cases like a refused connection and restart-token behavior, so the tool can be invoked and interpreted without additional assumptions.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning. It explains that repositoryId and status can be combined, that status is 'open' or 'closed', and that omitting both yields all reviews. It does not say where repositoryId comes from, such as list_repositories, but the core filtering semantics are clear.

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

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

States exactly what the tool does: lists reviews with newest activity first, with explicit filtering by repositoryId and/or status. It also clarifies the scope ('list every review across all tracked repositories') and distinguishes the review object's semantics from commit-level details, so an agent can tell it apart from get_review.

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 invocation context: use filters when targeting a subset, omit both to list everything, and use git when actual changed content is needed. It does not explicitly name sibling alternatives such as get_review for single-review lookups, so it stops short of full when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds a crucial nuance: the working copy on disk is never touched. This clarifies the exact scope of destruction, which is not inferable from annotations alone. It aligns with the destructive hint but provides essential context that the operation does not affect local files.

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 no filler. The first sentence states the action, the second clarifies a key behavioral distinction. All information is front-loaded and essential, making it highly concise and well-structured.

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

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

For a simple one-parameter tool with no output schema and annotations covering destructive/idempotent behavior, the description provides the essential scope (removal from GitWarren, not disk). It is largely complete, though it could optionally mention the effect on associated data (e.g., reviews) or return behavior, but these are not critical 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?

The schema has no description for the required 'id' parameter (0% coverage), and the tool description does not mention the parameter at all. The meaning of 'id' is likely inferable from the context (repository ID), but the description fails to explicitly state what it refers to, leaving the agent to rely on assumptions. With zero schema coverage, the description should compensate but does not.

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

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

The description states a specific verb ('Stop tracking') and resource ('a repository'), and immediately distinguishes what it does not do ('the working copy on disk is never touched'). This is a clear, non-tautological statement that differentiates it from sibling tools like get_repository or add_repository.

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

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

The description implies usage ('Stop tracking a repository') but does not explicitly contrast with alternatives or state when not to use it. There are sibling tools like remove_review for other resources, but no explicit routing guidance is provided. The intent is clear from context, but it lacks explicit when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable context by specifying that only the review record is affected and that no repository content is touched. It also mentions the non-destructive alternative. While it doesn't cover errors or permissions, for a simple destructive operation with annotations already present, this is strong behavioral disclosure.

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

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

Two sentences with no filler. The primary action is front-loaded, followed by a precise scope clarification and a useful alternative. Every sentence earns its place, and the structure is easily scannable.

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

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

For a destructive tool with a single parameter, the description is complete. It explains what the tool does, what it doesn't do, and when to use an alternative. With annotations covering safety and no output schema required, nothing critical is missing.

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

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

Schema description coverage is 0% and the description does not explicitly explain the 'id' parameter. While the parameter name and tool name imply it is the review ID, the description adds no additional semantics beyond what the schema (type, constraints) already states. For a low-coverage case, the description should compensate by clarifying the meaning of the ID, but it fails to do so.

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

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

The description opens with a clear verb and resource: 'Delete a review.' It immediately disambiguates scope by stating it removes only the review record and nothing in the repository, and contrasts with the 'closed' status alternative. This clearly distinguishes it from sibling tools like delete_review_comment or update_review.

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 when to use this tool (when you want to delete) and when not to (when you want to file away a review, use 'closed' status instead). This is a direct, actionable usage guideline with an alternative provided.

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 indicate a write operation (readOnlyHint false) and the description reinforces that by 'Add a message.' It goes well beyond annotations by disclosing side effects: file copying and path rewriting, size limits, behavior when a path fails (left as text), and detailed link semantics (guiUrl vs webUrl, token behavior, when each applies). This is extensive behavioral disclosure that fully prepares the agent for side effects and edge 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?

The description is long but every section serves a purpose: purpose, usage distinction, image formatting, and link semantics. It is front-loaded with the core purpose, then structured logically. While it could be trimmed slightly, the density of critical information justifies its length.

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

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

Given the tool's complexity (image handling, link nuances) and lack of output schema, the description covers all necessary ground: how to construct body, what happens with paths, how to interpret guiUrl and webUrl, and what to do when links fail. An agent can confidently invoke this tool without additional information.

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?

Although schema coverage is 0%, the description adds significant meaning: it explains that threadId comes from list_review_comments and gives a detailed explanation of how to format body for images, including markdown syntax, alt text, space handling, and size limits. This far exceeds what the schema provides, fully compensating for the lack of 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 clearly states the action: 'Add a message to an existing thread.' It also distinguishes from the sibling tool by saying 'Use this rather than opening a new thread when responding to something someone already raised,' which differentiates it from add_review_comment. The purpose is specific, unambiguous, and directly contrasts with an alternative.

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

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

Explicit guidance is given on when to use this tool: 'Use this rather than opening a new thread when responding to something someone already raised.' It also directs the agent to get thread ids from list_review_comments. The description further provides detailed usage for images and links, making the intended context crystal clear.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond these: it notes that resolving records who did it, that it never deletes messages (reinforcing non-destructive), and explains the behavior of returned links (guiUrl, webUrl) and token handling. This enriches the behavioral profile without contradicting the annotations.

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

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

The description is detailed and well-structured with paragraphs, but it is somewhat verbose. The front-loaded purpose is clear, yet the extensive explanation of guiUrl/webUrl and token behavior could be trimmed for brevity while preserving essential usage guidance. It is informative but not concise.

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

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

Given the tool's complexity (mutation with side effects and link outputs) and the absence of an output schema, the description covers necessary aspects: it explains the mutation's recording behavior, non-destructive nature, and the two link types and when to offer each. This is sufficient for an agent to call the tool and handle results appropriately.

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

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

With 0% schema description coverage, the description must compensate, and it does for the `resolved` parameter: it explains that `true` marks the point addressed and `false` reopens it. `threadId` is not elaborated, but its purpose is self-evident from the parameter name and the tool's purpose. The description adds semantic value for the key 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 opens with 'Mark a discussion settled, or reopen one,' which is a specific verb+resource pair that clearly identifies the tool's action. It explicitly states the two possible outcomes (resolve or reopen) and ties them to the `resolved` parameter, making the purpose unmistakable and distinct from sibling tools like `update_review_comment` which handles content edits.

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 situational context by saying 'Set `resolved` to true once the point has been addressed, false to bring it back,' which implies when to use it. However, it does not explicitly compare against alternatives like `update_review_comment` or `delete_review_comment`, nor does it state when not to use this tool, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds behavioral detail by explaining that a new path is 'validated and resolved exactly as it is when adding', which is useful beyond annotations. It does not contradict annotations, and it provides a specific validation 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-loaded with the core action and then a usage constraint. No wasted words; every sentence contributes to understanding the tool's function and parameters.

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 three parameters (one required), no output schema, and no nested objects, the description covers the primary operations, parameter requirements, and validation behavior. It does not mention return values or edge cases, but these are not essential given the simplicity. The description provides enough for an agent to call the tool correctly.

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

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

With schema description coverage at 0%, the description must compensate. It explains the role of name and path by stating 'Provide at least one of name or path' and clarifies path validation behavior. The required id is not explicitly described, but its purpose is obvious from context and sibling tools. The description adds meaning beyond the bare schema types and optionality.

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 rename a repository or repoint it to a new working copy path. It uses specific verbs ('rename', 'repoint') tied to the resource ('tracked repository') and distinguishes from siblings like add_repository, remove_repository, and list/get by focusing on updating existing repositories.

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 indicates when to use the tool ('Rename... or repoint...') and provides a concrete usage constraint ('Provide at least one of name or path'). It also references that path validation behaves as in add_repository, giving context. However, it does not explicitly mention when not to use it or alternatives, though the sibling names 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?

The description goes far beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). It explains validation behavior ('New refs are validated exactly as they are on creation'), the mandatory presence of at least one field, and, most notably, the detailed behavior of the returned guiUrl and webUrl links, including how to handle a user reporting a refused connection and the token/cookie mechanism. This is rich behavioral disclosure that helps the agent understand side effects and interpretation of results.

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 structured in two paragraphs, front-loaded with the core purpose and requirement, then diving into link behavior. While it is somewhat long, every sentence adds value—especially the link explanations, which are crucial for correct agent behavior. There is no redundancy, and the structure logically separates the action from the result handling. It is appropriately detailed without being verbose.

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 6 parameters, no output schema, but informative annotations, the description covers the essential aspects: what can be updated, the requirement for at least one field, validation, and the detailed semantics of the returned links (guiUrl and webUrl), including how to present them and how to troubleshoot a broken link. This is sufficient for an agent to invoke the tool correctly and interpret its result. The absence of an output schema is mitigated by the thorough explanation of the link 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?

Schema description coverage is 0%, so the description must compensate. It names the modifiable fields ('title, description or endpoints') and status, and clarifies that at least one must be provided. It also mentions validation for refs. However, it does not individually explain parameters like id, baseRef, headRef, or description beyond their types in the schema. The description adds some meaning but does not fully document each parameter's semantics, leaving gaps for an agent trying to construct valid input.

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 clear purpose: 'Change a review's title, description or endpoints, or set its status to closed or open again.' It explicitly lists the mutable fields and the status option, distinguishing it from sibling tools like create_review, remove_review, and get_review. The verb 'change' and resource 'review' are specific and 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 a clear usage requirement: 'Provide at least one field.' It also explains when to offer guiUrl vs webUrl, which guides post-update behavior. However, it does not explicitly state when to use this tool versus alternatives (e.g., create_review for new reviews), though the context of updating an existing review is implied by the tool name and sibling list. The guidance is adequate but not exhaustive.

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?

This is unusually transparent. The description discloses ownership constraints, the guiUrl return field and its behavior even when GitWarren is not running, token/cookie behavior across restarts, and the conditional webUrl field. These details go well beyond what the annotations provide and are genuinely useful for invoking the tool correctly.

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 well-organized and front-loaded with the core purpose, but it is long and spends significant space on edge cases around guiUrl, tokens, cookies, and webUrl. While much of that detail is relevant, the overall length is high for a simple two-parameter update tool.

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 that there is no output schema, the description thoroughly covers the return fields and their behavior, including guiUrl and webUrl conditions, plus the ownership permission that affects when the tool may be used. The information is sufficient for an agent to decide whether to call the tool and what to do with the result.

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% property description coverage, so the description carries the burden of explaining the parameters, but it never names or explicitly maps `id` or `body`. The phrase 'Replace the text of one message' hints at what `body` does, and 'one message' implies `id`, but the agent is left to infer parameter semantics from names and context.

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

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

The description opens with a specific verb and resource: 'Replace the text of one message.' It also clarifies the intended scope by saying an agent can only edit messages written by its own tool. However, it does not explicitly distinguish this tool from siblings like add_review_comment or reply_to_review_comment, so it stops short of full differentiation.

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 when-to-use and when-not-to-use guidance: 'correcting yourself is expected, rewriting someone else's review is not.' It does not name alternative tools or explicitly route the agent to a sibling for other cases, so the guidance is strong but lacks explicit alternatives.

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