Markdown by mdedit.ai

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the atomicity behavior ('Atomically apply') and the idempotency-relevant instruction to reuse the commandId on retry, which is valuable context beyond the annotations. It doesn't mention permissions or reversibility, but the atomicity and idempotency details are meaningful.

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 first sentence states the action and atomicity, the second gives the critical usage instruction about which IDs to use. 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?

The tool has an output schema, so return values are covered. The description covers the core behavior, atomicity, and ID sourcing. It doesn't mention what happens if the suggestion is already accepted or if the IDs are stale, but for a mutation tool with annotations covering destructive/idempotent hints, this is adequate.

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 71%, so the schema documents most parameters. The description adds meaning by telling the agent to use exact IDs from add_suggestion or list_review_threads, and the commandId description in the schema already explains idempotent retry. The description doesn't need to repeat all parameter details, but it does add value for the key IDs.

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 action: 'Atomically apply an existing review suggestion to the document and mark it accepted.' It specifies the resource (review suggestion) and the effect (apply and mark accepted), and distinguishes it from siblings like reject_suggestion by naming the exact IDs to use.

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

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

The description gives explicit guidance on which identifiers to use ('Use the exact suggestionId and targetId returned by add_suggestion or list_review_threads'), which is a clear usage instruction. It doesn't explicitly state when not to use this tool or name alternatives like reject_suggestion, but the context is clear enough for an agent to select 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 cover read/write, idempotency, and non-destructiveness; the description adds non-obvious behavior: comments do not directly change document prose, natural names are accepted, and threadId/targetId are returned for downstream calls. 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 concise sentences that front-load the purpose and then add scoping and return-value context. Every sentence earns its place with 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?

For an 8-param tool with 63% schema coverage and an output schema, the description covers the core workflow and identifier flexibility well. It is slightly incomplete about the optional targetId input, but the anchor structure is clear from the schema and the output schema covers return details.

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 63%, and the description adds meaningful guidance: prefer human-readable titles and workspace names over internal identifiers, internal routing IDs are optional, and the returned IDs are meant for reply/resolve. It does not fully elaborate anchor or body semantics, preventing a 5.

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

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

States a specific verb and resource ('Add an anchored review comment'), conveys non-destructive scope, and distinguishes from document-editing tools. The mention of return IDs for reply_to_thread and resolve_thread also separates it from thread-operation 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?

Implies use when the user wants an anchored review comment rather than a prose edit, but never explicitly names alternatives such as add_suggestion or says when not to use it. The downstream mention of reply_to_thread and resolve_thread is workflow context, not a when-to-use guide.

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 indicate a mutating, idempotent, non-destructive operation, and the description does not contradict them. It adds useful behavioral context: the tool resolves natural names and returns suggestionId/targetId for downstream accept/reject calls, implying no direct document modification.

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 the core action front-loaded, followed by parameter flexibility and return-value workflow. Every sentence contributes useful information with no filler.

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

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

For a 9-parameter tool with an output schema and idempotency annotations, the description plus schema covers the main usage decisions: natural-name resolution, optional internal IDs, and downstream accept/reject workflow. The remaining gaps around targetId and anchor selection are noticeable but not crippling.

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 56%, and the description adds useful meaning for the name/identifier parameters and characterizes 'replace' as the replacement text. However, it does not clarify the input semantics of targetId, the optional note field, or how to choose between the quote and range anchor shapes, leaving meaningful gaps.

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 (Add), a clear resource (anchored replacement suggestion), and the purpose (for a human to accept or reject). It also differentiates itself from the sibling accept_suggestion/reject_suggestion tools by describing creation rather than resolution.

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 conveys clear usage context: this tool creates a proposal rather than applying a change, and natural workspace/document names are acceptable, so the agent does not need to ask for internal IDs. It does not explicitly name alternatives like add_comment or edit_article, but the workflow is reasonably 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?

Beyond the annotations, the description discloses the asynchronous lifecycle, the opaque nature of the returned jobId, the need to poll get_conversion_status, and the user-facing rule not to show the jobId. It also notes the document need not exist in mdedit. This does not contradict the readOnlyHint annotation.

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

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

Three sentences with every sentence earning its place: what it converts, the asynchronous workflow, and which sibling to use instead. Purpose is front-loaded and there is no redundant prose.

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 async conversion tool with fully documented parameters and an output schema, the description supplies the complete invocation pattern: pass content directly, choose a target format, poll with the returned jobId, and use start_article_export for stored documents. Nothing essential for invoking it correctly 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 100%, so the schema already documents content, to, from, and fileName. The description adds only high-level confirmation (pass content directly) and format examples already present in the schema, so the 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 names a specific verb (Convert), the input resource (Markdown or HTML the caller already has), and concrete output formats (Word, PDF, HTML, LaTeX, EPUB). It also distinguishes itself from start_article_export by clarifying this is for content passed directly, not documents stored in mdedit.

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 when to use the tool: when content already exists and is passed directly. It also gives the exclusion and alternative: 'To export a document already stored in mdedit, use start_article_export instead,' and routes the caller to get_conversion_status for the asynchronous result.

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 idempotentHint=true, readOnlyHint=false, and destructiveHint=false, and the description adds 'durable' and 'accessible workspace' as light behavioral context. It does not disclose permission requirements, conflict behavior, or what 'accessible workspace' means operationally, but it does not contradict the annotations.

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

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

Two sentences, with the core purpose front-loaded and the workspace-selection guidance in a single follow-up sentence. 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?

With seven parameters, low schema coverage, and an output schema present, the description covers the workspace ambiguity but leaves folderId and collaborative behavior unexplained. It is adequate for a simple create operation but not fully complete for all optional inputs.

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 only 43%, so the description should compensate; it does add value for the workspace parameters by explaining when to omit workspaceId and when to use workspaceName. However, it does not clarify folderId or collaborative semantics, and title/content are left to the schema's basic types.

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 a durable Markdown Document with initial content') and clearly signals a new-document action, distinguishing it from sibling tools like edit_article, read_article, and publish_article. The title reinforces this 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?

The description gives conditional guidance for workspace selection ('Omit the workspace selector... or pass workspaceName...'), which is useful, but it does not explicitly state when to choose this tool over alternatives such as edit_article or list_workspaces. The intended use is implied by the verb and resource rather than explicitly contrasted.

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 provide readOnlyHint=false, destructiveHint=true, and idempotentHint=true, covering safety and idempotency. The description adds 'apply anchored edits', which clarifies the method of modification beyond annotations, but does not describe side effects, failure modes, or concurrency behavior. Given the annotations cover the main behavioral concerns, a 3 is appropriate.

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

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

Two sentences, with the key intent ('apply anchored edits') front-loaded. It is concise but not overly terse; it conveys the core behavior without wasting words. Some redundancy with the title is acceptable.

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 this is a complex edit tool with many operation types and the schema is extensive (71% coverage), the description alone is sparse. It doesn't mention how to construct operations, what the output represents (though output schema exists), or any error/rollback notes. The schema and output schema carry much of the burden, but the description could elaborate more on usage patterns. It's adequate but leaves 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 description clarifies that natural workspace names and document titles are preferred over internal identifiers, which adds meaning to parameters like workspaceName, articleTitle vs workspaceId, articleId. This is valuable beyond the schema's per-parameter descriptions, which are already detailed but don't explain the preference.

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 applies anchored edits to documents, which is a specific verb+resource. It also mentions the 'authoritative ordinary or collaborative document service', which hints at scope but is vague. It does not explicitly distinguish from sibling edit-like tools (e.g., add_suggestion, accept_suggestion), but the general purpose is clear.

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 alternatives. It does not say 'use this to modify existing documents' or mention any exclusions. It only hints at parameter preferences (natural names vs IDs), but not tool selection 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The descripption adds useful behavior beyond annotations: it returns a download link when complete and does not expose the internal job identifier. It does not cover failure or polling behavior, but the safety profile is already covered by annotations.

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

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

Two sentences with no filler. The purpose is front-loaded, and the behavioral detail about the download link and hidden internal identifier is compact and relevant.

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, one-parameter status tool with an output schema, the description plus annotations are largely sufficient. It could add a note about polling or invalid job IDs, but the core invocation path 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?

The schema has no description coverage for the single required jobId parameter. The description implies that the jobId relates to an export started by start_article_export, but it does not explicitly state that jobId is the identifier returned by that call or provide format details. It provides minimal compensation for the 0% schema 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 uses a specific verb ('check') and resource ('an export started by start_article_export'), and it states the distinctive outcome: returning a download resource link when complete. This clearly distinguishes it from sibling status tools like get_conversion_status and get_publish_status by tying it to the export workflow.

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 makes the usage context clear: it is for checking an export that was started by start_article_export. It does not explicitly list when-not-to-use alternatives, but the resource scoping is unambiguous enough to guide selection.

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 operation as read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond that: it returns a download link when complete and does not expose the internal job identifier. It does not mention pending or error states, but the annotations and output schema cover the safety profile.

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 front-loads the action and resource, then efficiently packs output behavior and a privacy trait with no filler. Every clause 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 one-parameter, read-only polling tool with a full output schema and strong annotations, the description covers purpose, origin, and completion behavior. It could be more explicit about where jobId comes from and what the response looks like while the conversion is still running, but those are minor 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 schema only defines jobId as a non-empty string and has 0% description coverage, so the description must carry meaning. It implies jobId identifies a conversion created by convert_document, but it never explicitly says 'pass the jobId returned by convert_document' or explains the format. This adds moderate value but leaves the source of jobId slightly implicit.

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

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

States a specific verb ('Check') and a specific resource ('conversion started by convert_document'), clearly distinguishing it from the sibling convert_document tool. It also tells the agent what the result is: a download resource link once the conversion is complete.

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 ties the tool to conversions started by convert_document, making the precondition clear: use this after starting a conversion there. It does not list exclusions or alternative tools, but the source-tool reference provides enough context for correct 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?

Annotations already establish read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful context by stating that presence includes both people and agents and that it reflects current state, which goes beyond the annotations. There is 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?

Two focused sentences, with the action and subject front-loaded and no wasted wording. The second sentence efficiently conveys the key routing guidance without elaboration.

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 presence-listing tool with a full output schema and fully described optional parameters, the description is complete. It covers what the tool returns conceptually, how to reference documents and workspaces, and when internal identifiers are unnecessary.

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 each parameter already has a meaningful description, so the schema carries most of the parameter semantics. The description adds a useful summary of preferring natural names over internal identifiers, but it does not materially extend what the schema says.

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 ('List') and a precise resource ('people and agents currently present in a collaborative document'), making the tool's purpose immediately clear. It is also distinct from sibling tools such as get_publish_status or read_article, since presence is a unique concept.

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 practical guidance: prefer natural workspace names and document titles, and treat internal identifiers as optional. It does not explicitly name alternative tools or exclusion conditions, but the usage context is clear enough for an agent to select this tool appropriately.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the notion of a 'stable' public-link URL, which is a useful behavioral detail, but does not disclose any additional traits like rate limits, authentication, or return format variations. With annotations covering the safety aspects, a score of 3 is appropriate.

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

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

The description is a single sentence that front-loads the core purpose, then provides parameter guidance without any filler. It is concise, structured, and every clause earns its place, making it easy for an agent to parse quickly.

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

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

The tool has an output schema, so return values are already defined elsewhere. The description covers the essential invocation details: what it returns and that natural names are accepted. A minor gap is that it does not explicitly state whether at least one identifier is required, though the schema marks all parameters as optional, leaving some ambiguity for edge cases. Overall, it is nearly complete for a read-only status 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 100%, and each parameter already includes guidance such as 'Prefer this over asking the user for an internal document identifier.' The description's statement that internal identifiers are optional adds no new semantic meaning beyond what the schema provides, aligning with the baseline of 3 when schema covers parameter meaning.

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 ('Get'), a clear resource ('stable public-link URL and publication state'), and the target ('Markdown Document'). It distinguishes from siblings like get_article_export_status and get_conversion_status by focusing on publication status and public link, making the purpose unambiguous.

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

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

The description provides clear context on parameter selection—'Accepts natural workspace names and document titles; internal routing identifiers are optional'—which tells the agent how to invoke the tool. However, it does not explicitly mention when to prefer this tool over alternatives or when not to use it, though the distinction is implied by the read-only nature and specific resource.

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 establish readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context beyond those annotations: results are intentionally bounded, full content is never returned, and workspace selection can be omitted in certain cases. There is 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?

Three sentences with no filler. The core purpose is front-loaded, and each subsequent sentence adds distinct, actionable guidance: bounded results, workspace selector behavior, and query usage.

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 read-only annotations, an output schema, and no required parameters, the description is sufficient for an agent to decide when to call this tool and how to handle workspace disambiguation and pagination. The only minor gap is not naming a sibling explicitly, but the 'without returning full content' phrase already conveys the main boundary.

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

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

Schema coverage is only 60%, and the description compensates by explaining query's purpose ('use query for a title instead of loading every page') and by clarifying workspaceName versus workspaceId usage. Cursor and workspaceId already have schema descriptions, but limit lacks descriptive guidance. Overall, the description adds meaningful parameter-level decision support.

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 'Search or page through Markdown Documents in a workspace without returning full content,' naming the action, resource, scope, and a key distinguishing constraint. This clearly separates it from read_article (which returns full content) and from editing/publishing 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 concrete conditions: omit the workspace selector for single-workspace users, pass workspaceName when the user chose a workspace by name, and use query for a title search rather than loading pages. It does not explicitly name an alternative sibling like read_article for when full content is needed, so it stops short of a full when-not recommendation.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by stating that natural workspace names and document titles are accepted and internal routing identifiers are optional. This helps an agent understand how the tool resolves identifiers.

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, tight sentence that front-loads the action and resource, then adds the key routing detail about natural names and optional IDs. Every word earns its place; there is no filler or repetition of the title.

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 an output schema and informative annotations, the description covers the core calling pattern well: list review threads for a document, using natural names when available. The main gaps are the undocumented status and targetId parameters and the lack of explicit sibling differentiation, but neither prevents correct invocation in the primary natural-language use case.

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 clarifies the natural-name versus internal-ID strategy, which maps directly to articleTitle, workspaceName, articleId, and workspaceId. However, status and targetId have no schema descriptions and are not mentioned in the free-text description, leaving two parameters semantically unexplained despite 67% schema 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 states a specific verb and resource: 'List review comments, highlights, and suggestions for a document.' This clearly separates it from siblings like list_articles and list_workspaces, and the word 'List' distinguishes it from mutation siblings like add_comment, reply_to_thread, and resolve_thread.

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

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

The description implies when to use the tool: when the user wants to see review feedback on a document. However, it never explicitly states when to prefer this over alternatives such as add_comment, reply_to_thread, or resolve_thread, nor does it provide any exclusion guidance. The natural-name routing note is helpful, but it is more invocation guidance than tool-selection 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context by scoping results to the signed-in user and explicitly excluding document content, which goes beyond raw 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 that front-loads the action and resource, then adds two useful behavioral clarifiers without wasting words. Every clause 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 zero-parameter list tool with annotations covering safety and an output schema present, the description is fully sufficient. An agent knows what it lists, who it lists for, and what it intentionally omits.

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 baseline is 4. There is no parameter meaning for the description to add; the schema is already complete with an empty properties object.

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'), a precise resource ('mdedit workspaces'), and the scope ('available to the signed-in user'). It also explicitly distances itself from returning document content, distinguishing it from content-returning sibling tools like read_article and list_articles.

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 intended context: use it when the user needs workspace names/metadata, and it clarifies that document content is not included. It does not explicitly name alternatives or excluded cases, but the resource distinction is strong 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?

Beyond the annotations, it discloses that later durable edits automatically update a live link at the same URL, that snapshot mode freezes an artifact, that existing links keep their mode unless overridden, and that user confirmation is required. These are meaningful behavioral traits not carried by readOnlyHint/idempotentHint/destructiveHint.

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 tight sentences front-load the core purpose and then add only high-value behavioral and permission details. No filler 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?

Given nine parameters, nested objects, and an output schema, the description plus schema covers permissions, confirmation, mode selection, identifier strategy, and idempotency. An agent has enough to call this correctly without hunting for missing 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?

With 78% schema description coverage, the schema already documents most parameters. The description adds a compact conceptual layer—natural names vs optional internal routing identifiers and live vs snapshot mode behavior—that helps an agent pick the right fields, though it does not elaborate customSlug or seoMetadata.

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 'Publish or update a Markdown Document at a public mded.it link', which names a specific verb, resource, and destination. It also clarifies that natural workspace names and document titles are accepted, distinguishing the routing style from ID-only 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?

It gives clear context for invocation: natural names are preferred, internal IDs are optional, new links default to live, and publishing:write plus explicit user confirmation are required. It does not name sibling tools or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds the 'current saved' framing and optional-identifier input behavior, but not much behavioral context beyond what annotations and the output schema provide.

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 the operation and target front-loaded and the key input flexibility stated second. There is no filler or repetition of structured fields.

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?

Four optional parameters are fully documented, annotations cover safety and idempotency, and an output schema exists, so the essential calling information is present. Naming the closest alternative sibling, such as render_article, would make it slightly more complete, but 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 coverage is 100% and each parameter already has thorough guidance, such as 'Prefer this over asking...' and 'Omit it when...'. The description's summary about natural names and optional internal identifiers is useful but does not add meaning 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 names a specific operation (reading) and a specific resource ('current saved Markdown content and metadata for a document'), so an agent can tell what the tool does. It does not explicitly distinguish this from siblings like render_article, but the verb and resource are 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?

The description gives a clear usage cue: it accepts natural workspace names and document titles, with internal identifiers optional. It stops short of naming alternatives or stating when not to use this tool, so it lacks full exclusion 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 mark it read-only; the description adds useful context by guaranteeing it is component-only, privacy-safe, and never accepts document content, visible identifiers, review prose, or URLs. This fills in important behavioral constraints beyond what the annotations provide.

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 only two sentences, front-loaded with the tool's category and free of filler. It could add one usage-oriented sentence without becoming bloated, but it is otherwise 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 flat enum-only tool with annotations and an output schema, the definition is nearly sufficient, but it lacks parameter-level guidance and a concrete usage trigger. An agent may still be unsure when to send event='action' versus filling in action, focus, or status.

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 the six parameters, but it only says what parameters cannot contain. The enum lists help, yet there is no guidance explaining relationships between event, action, focus, or when each optional parameter 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 title supplies the verb ('Record') and the description names the resource as component-only privacy-safe operational telemetry, which clearly separates it from the content-editing sibling tools. The description is a noun phrase rather than a complete action sentence, so it stops short of a 5.

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 use for privacy-safe telemetry by emphasizing that it never accepts document content or identifiers, but it never explicitly says when to call it or names an alternative. It gives contextual guidance without a clear trigger or exclusion.

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 provide idempotentHint=true and destructiveHint=false, and the description adds the critical behavior that it does not change the document, which is beyond the annotations. It also instructs to use exact IDs to avoid side effects, reinforcing idempotency. There is no contradiction; it complements the readOnlyHint=false by clarifying that despite being a mutation, it doesn't alter the document. This is useful context for safety.

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 that is direct and action-oriented, front-loading the purpose and the key constraint. It includes necessary guidance about ID sources without excessive detail. Loses a point because it could be slightly more explicit about the source of targetId, but overall it is concise and effective.

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 7 parameters, 2 required, and an output schema, the description is fairly complete. It explains the core behavior, the source of IDs, and the no-change guarantee. The output schema handles return value details, so not needed. However, it doesn't mention the authorization or the relationship to threads, but that is minor given the context of using prior tool outputs. Overall, a solid description for a mutation tool with annotations covering idempotency.

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 71%, meaning some parameters are undocumented in the schema (e.g., suggestionId, targetId lack descriptions). The description explicitly instructs to use exact suggestionId and targetId from prior calls, providing semantics for these critical parameters. It also clarifies that targetId should come from the same source, filling the gap. Other parameters like articleTitle and workspaceName have their own schema descriptions, so the description adds value where needed.

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 ('Mark an existing review suggestion rejected'), the target resource ('review suggestion'), and the key constraint ('without changing the document'). It distinguishes from sibling accept_suggestion by emphasizing rejection without modification, which is a specific, non-tautological 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?

It specifies to use the exact suggestionId and targetId returned by add_suggestion or list_review_threads, which is clear when-to-use guidance. It does not explicitly mention when not to use it (e.g., for accepting) or name alternatives, but given the sibling list shows accept_suggestion, a slight gap remains. However, the instruction to not change the document implies a read-like mutation, and the source of identifiers is well 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 already provide readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds context about opening in the mdedit reader and accepting natural identifiers. It does not disclose behavior around focus modes or side effects, but no annotation 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 short and front-loaded with the core action, followed by identifier guidance and usage context. The list of request types is somewhat broad, but overall every sentence contributes useful 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 output schema and annotations, return values and safety are already covered. The description covers identifier selection and after-creation context, but it lacks explicit sibling disambiguation and does not explain the meaning of focus modes like export, publish, or review, leaving some ambiguity for an agent.

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 80%, so the schema already documents natural names, internal identifiers, and when to omit them. The description reinforces that internal identifiers are optional, but adds little beyond what the schema already states, 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 opens with a clear verb and object: 'Open the current saved document in the mdedit reader.' It also clarifies that natural workspace names and document titles are accepted, and internal identifiers are optional. However, it does not explicitly distinguish this tool from siblings like read_article, publish_article, or start_article_export.

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

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

The description gives explicit context: use it after creation or updates and for open, read, show, preview, export, publish, or review requests. But it does not explain when to prefer dedicated siblings such as publish_article or start_article_export, nor does it state exclusions, so the guidance is broad and potentially overlapping with other tools.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description contributes almost no extra behavioral context beyond restating that the action targets an existing thread; it does not mention where the reply appears, permission needs, or retry safety.

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 filler and front-loads the action and object. It is efficient, though its brevity borders on under-specification.

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 mutation with closely related siblings like add_comment, resolve_thread, and list_review_threads, this description is too sparse. It leaves identifier selection, retry behavior, and differentiation from add_comment unexplained, so an agent must infer critical usage details from other sources.

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 leaves body, targetId, and threadId without descriptions, and the tool description does not compensate by explaining them. It also does not clarify when to use articleId versus articleTitle or targetId versus threadId, so the moderate 63% schema coverage is not supplemented.

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, 'Reply,' and identifies the resource, 'existing review thread.' It clearly indicates a write action on a thread, but it does not explicitly differentiate this from sibling tools such as add_comment or resolve_thread.

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

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

There is no guidance about when to use this tool versus alternatives, nor any mention of prerequisites like needing to find the thread first via list_review_threads. The phrase 'existing' only implies one prerequisite and does not help an agent choose between this and add_comment.

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 indicate this is a non-readonly, idempotent mutation, so the bar is lower. The description adds the behavioral note that the thread must already exist and that the IDs must come from add_comment, and warns against commandId. However, it does not disclose what 'resolving' does to the thread state or that commandId is still required for idempotency, which is a notable gap.

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

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

The description is a single, front-loaded sentence with no filler. Every phrase carries meaning: the action, the required ID provenance, and the exclusion of commandId as an identifier.

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 the rich schema, the description's 'not commandId' phrasing is ambiguous because commandId is a required parameter in the schema. The description fails to clarify that commandId must still be supplied for idempotency and that 'not commandId' means 'do not use it as the thread identifier'. This creates a potential conflict for an agent trying to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's warning about using threadId/targetId and not commandId largely repeats what the schema already says in the parameter descriptions. It adds minimal semantic value beyond the structured field 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 clearly states the action ('Resolve an existing review thread') with a specific verb and resource. It also adds the key detail that the thread must be identified by the exact threadId and targetId returned by add_comment. It does not explicitly contrast with sibling tools, but 'resolve' is distinct from 'reply_to_thread' and 'list_review_threads'.

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 operational guidance: use the exact threadId and targetId from add_comment, and do not use commandId as the identifier. This is a useful exclusion that prevents a common mistake. It does not discuss when to prefer resolve_thread over alternatives, but the action is specific enough that the intended context is evident.

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 contradicts the annotations. Annotations declare readOnlyHint=true, implying the operation does not modify state, but the description says 'Start an asynchronous export' which launches a job and side effects (creating an export). This is a serious inconsistency that could mislead an agent into assuming no side effects. Beyond the contradiction, the description adds some useful behavioral context (opaque jobId, don't expose to user) but fails to disclose any permission or rate-limit requirements, and the contradiction dominates.

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 ('Start an asynchronous export'), and packs essential operational details (jobId polling, internal vs natural names, don't expose jobId) without waste. Every sentence adds necessary information for correct invocation.

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 asynchronous nature, the description covers the key interaction pattern (poll with jobId) and the privacy requirement (don't show jobId). The output schema presumably documents the jobId return, so its absence here is acceptable. However, it omits any mention of errors or prerequisites (e.g., document must be saved), and does not address concurrency or rate limits. The schema covers format options, so completeness is reasonably high, but not exhaustive.

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 adds meaning beyond the schema by stating that natural workspace names and document titles are accepted and that internal routing identifiers are optional. This clarifies the dual-identification approach and reinforces which parameters to prefer, going beyond the schema's descriptive comments. With 80% schema coverage, the baseline is 3, but the description's explicit guidance on when to use which identifier adds value.

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 an asynchronous export) and the resource (current saved document). It also distinguishes itself by noting the asynchronous nature and the presence of a jobId for polling, which is not mentioned in sibling tools like convert_document or render_article. The purpose 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 clear guidance on how to use the tool after invocation: pass the jobId to get_article_export_status and never show jobId to the user. It also hints at parameter selection by mentioning natural workspace names and document titles are accepted. However, it does not explicitly state when to prefer this over alternatives like convert_document or render_article, leaving the when-to-use versus siblings implicit.

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

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

Annotations already flag destructive and non-read-only behavior, and the description adds meaningful context beyond those hints: it requires publishing:write permission and explicit user confirmation. This surfaces the key safety and authorization considerations 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?

Three sentences, each earning its place: the core effect, the identifier strategy, and the required permission/confirmation. The most important behavioral fact 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 destructive tool with detailed schema, output schema, and annotations, the description covers the essential operational constraints: what action is performed, how to identify the target, what permission is needed, and that user confirmation is mandatory. 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 coverage is 100%, so the baseline is 3. The description condenses the identifier-optionality guidance already present in the parameter descriptions but does not add substantial new meaning 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 opens with a specific action and resource: 'Disable a Markdown Document public link.' This clearly distinguishes the tool from siblings like publish_article and edit_article by describing the unpublishing effect rather than merely restating the name.

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 by explaining that natural workspace names and document titles are acceptable and that internal identifiers are optional. It also states the required permission and explicit user confirmation, which are important preconditions, though it does not explicitly name alternatives or exclusion cases.

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