Markdown by mdedit.ai

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

The description adds behavioral detail beyond the annotations by stating that the operation is atomic and that it marks the suggestion as accepted. Since annotations already flag the operation as destructive and non-idempotent, the added atomicity and state-change context is valuable and non-redundant.

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 core behavior is stated first, followed by the most important data-provenance rule. Every sentence contributes directly to 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 tool has seven parameters, only one is required, and an output schema exists, the description is mostly adequate. The main gap is that commandId has no explanation anywhere, and the description does not clarify why targetId is mentioned even though it is not a required parameter. Still, the core calling pattern is sufficiently conveyed.

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 57%, and the description adds meaning for suggestionId and targetId by emphasizing they must be exact values returned by prior calls. However, commandId remains undocumented in both the schema and description, leaving an unclear role for a parameter in a destructive, non-idempotent operation.

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 specific action: atomically apply an existing review suggestion to the document and mark it accepted. It also distinguishes the operation from related sibling tools by focusing on existing suggestions and the acceptance outcome.

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: this tool is for applying an already-created suggestion, not for creating or rejecting one. It also instructs to use the exact suggestionId and targetId returned by add_suggestion or list_review_threads, giving an agent concrete data provenance 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 signal that this is a write operation (readOnlyHint=false) and not destructive. The description adds useful behavior beyond those flags: it explicitly says the tool does not modify document prose, accepts human-friendly names, and returns threadId/targetId for downstream operations. 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?

The description is two sentences, front-loads the core action and constraint, and every sentence contributes meaningful information. There is no filler or repetition of the tool name or schema 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?

Given the output schema exists, the description does not need to explain return values in depth, yet it still names the key downstream use of threadId and targetId. It covers the main input options and the non-destructive nature of commenting. The only notable omission is explicit guidance about when to choose add_comment over add_suggestion, but the prose-change distinction partially covers that.

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 usefully explains that workspaceName/articleTitle may be used instead of internal identifiers, which complements the schema descriptions for those fields. However, commandId and targetId remain undocumented in both the description and schema, and with 50% schema description coverage the description only partially closes the parameter-meaning gap.

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 object: 'Add an anchored review comment'. It also distinguishes the tool from suggestion tools by saying it does so 'without directly changing document prose', and it states the exact returned identifiers (threadId and targetId), making the purpose unmistakable.

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: natural workspace names and document titles are acceptable, internal routing identifiers are optional, and the returned identifiers are meant for reply_to_thread and resolve_thread. It does not explicitly say 'use this instead of add_suggestion', but 'without directly changing document prose' strongly implies the boundary between commenting and suggesting.

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

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

The description adds workflow behavior beyond the annotations: the suggestion is a proposal for a human to accept or reject, it returns identifiers for downstream tools, and internal routing IDs are optional/resolvable from natural names. The annotations already communicate non-read-only and non-idempotent characteristics, so the description's added workflow context is valuable. 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?

Three tight sentences with no filler. The main action is front-loaded, followed by parameter routing guidance and then the return-value tie-in. Every sentence adds useful information for selecting or invoking the 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 the complex 9-parameter schema and the presence of an output schema, the description covers the essential selection and invocation context: what the tool does, how to reference workspaces/documents naturally, and how the returned IDs connect to accept_suggestion and reject_suggestion. It could add explicit sibling exclusions or anchor-selection tips, but no major ambiguity remains.

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 usefully explains that natural workspace names and document titles are accepted and that internal routing identifiers are optional, which helps with several parameters. However, it does not explain the two anchor forms (quote-based vs range-based), the occurrence/context fields, or how to choose between them, so the low schema description coverage is only partially compensated.

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

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

The description opens with a specific verb and resource: 'Add an anchored replacement suggestion for a human to accept or reject.' The 'anchored' and 'replacement' qualifiers clearly distinguish it from add_comment, and the human accept/reject framing distinguishes it from direct document editing tools.

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

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

The description clearly situates this tool in a review workflow by stating it returns suggestionId and targetId 'for accept_suggestion or reject_suggestion.' It also gives practical guidance about using natural workspace names and document titles instead of internal IDs. It does not explicitly enumerate when-not cases like add_comment, but the context is clear and not misleading.

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 signal a non-read-only, non-idempotent mutation, and the description's 'durable' adds useful context that the document persists after creation. It doesn't disclose duplicate-title handling, required permissions, or whether creation implies publication (publish_article is a separate sibling), but with a full annotation set the burden on the description is lower.

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 delivers the core purpose and the second delivers the highest-value conditional guidance. Every sentence earns its place, and the action 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?

With an output schema present and a full annotation set, the description covers the essential creation semantics and the workspace decision rule. Minor gaps remain: no mention of the create-vs-publish relationship and no guidance on folderId or collaborative, but nothing blocks correct invocation for the common path.

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 33%, so the description must compensate. It does add the crucial disambiguation for workspaceName vs workspaceId vs omitting the selector. However, folderId and collaborative have no schema or description-level explanation, leaving two parameters under-documented.

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 ('Create') and resource ('durable Markdown Document with initial content'), clearly separating it from edit_article, publish_article, and read_article siblings. The 'durable' qualifier also distinguishes persistent document creation from ephemeral review artifacts like suggestions and comments.

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

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

Provides explicit conditional guidance on workspace selection: omit the selector for single-workspace users and pass workspaceName when the user named a workspace. It does not explicitly name when-not-to-use alternatives (e.g., edit_article for modifications), so it falls short of full alternative routing.

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 convey that the tool is destructive and not read-only, and the description adds useful behavioral context: this is not a one-shot edit but one that occurs through a persistent live session, implying statefulness and possible side effects beyond the single call. It does not contradict the annotations and adds meaningful non-schema information.

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

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

Two tight sentences deliver the core action, the session-based behavior, and the key routing guidance without wasted words. The most important behavioral information is front-loaded before the parameter-preference note.

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 — multiple operation types, rich anchor forms, and a destructive annotation — the description is functional for selection but thin on operational context. It does not clarify the lifecycle of the live session, the role of ifContentHash, or what happens if collaboration is not enabled; the rich schema and output schema carry much of the load.

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 already documents four of six parameters, and the description reinforces the routing guidance by saying natural workspace names and document titles are accepted while internal identifiers are optional. However, it does not explain the purpose of ifContentHash or add much beyond the existing parameter descriptions; the complex operations structure is left entirely to 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 verb ('Apply... edits'), a specific resource ('Markdown Document'), and a distinguishing method ('anchored edits') and context ('persistent live session when collaboration is enabled'). This makes it clear that the tool is for directly modifying an existing document rather than merely suggesting, commenting, converting, or publishing it.

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 usage condition by saying edits happen 'through a persistent live session when collaboration is enabled', which helps an agent identify the enabling environment. However, it does not state when to prefer this tool over siblings like add_suggestion, convert_document, or create_article, nor does it explain what to do when collaboration is not enabled.

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?

It discloses non-obvious behaviors well beyond annotations: new links default to live, later durable edits update the same URL, snapshots are frozen, existing links preserve their mode unless mode is supplied, and publishing:write plus explicit user confirmation are required. This richly informs the agent about side effects.

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 purposeful sentences front-load the core purpose, then cover routing, mode behavior, and permission/confirmation. No filler or redundant restatement of the name.

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

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

For an 8-parameter tool with a nested object, the description covers purpose, routing, mode semantics, permissions, and confirmation; an output schema covers return values. The only gaps are customSlug and seoMetadata semantics, which are not explained in either the description or their schema entries, though they are individually inferable.

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 75% schema coverage the schema already documents most parameters. The description adds real value by clarifying natural-name routing ('internal routing identifiers are optional') and the live/snapshot default behavior for mode. customSlug and seoMetadata remain lightly covered, but the description compensates for the main decision-critical parameters.

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

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

The description opens with a specific verb and resource: 'Publish or update a Markdown Document at a public mded.it link.' It further scopes behavior to live vs snapshot links, which clearly separates it from siblings like create_article/edit_article.

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

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

The description states the operation's context (publish/update at a public link) and gives mode-selection guidance ('Choose snapshot for a frozen artifact'). It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough for routing.

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?

The description adds a meaningful side-effect guarantee: it marks the suggestion rejected 'without changing the document.' With all annotation hints false, however, it leaves unstated whether the action is reversible, whether the suggestion must still be pending, and what happens to a rejected suggestion in reviewing workflows.

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 no filler; the key side-effect scope is front-loaded before the identifier instructions.

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 whose only required parameter is suggestionId, the description covers the essential call data and side-effect scope, and an output schema exists to describe the response. The main omission is commandId's role, but it is optional and likely not needed 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?

It adds provenance semantics for suggestionId and targetId, which the schema does not describe. Article and workspace identifier parameters are already explained in the schema, but commandId remains unexplained, 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?

The description states a specific action and resource: 'Mark an existing review suggestion rejected without changing the document.' This clearly distinguishes reject_suggestion from add_suggestion (which creates) and accept_suggestion (which accepts instead of rejecting).

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 tells the agent to use 'the exact suggestionId and targetId returned by add_suggestion or list_review_threads,' giving concrete prerequisites and identifier sources. It does not explicitly name when not to use or contrast reject vs accept, but the instruction is unambiguous.

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?

Annotations are all false and thus provide no safety or side-effect profile. The description only says 'reply', which implies a write action, but it does not disclose whether the thread state changes, whether the reply is appended, or any permissions or idempotency concerns.

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. It is concise, though the brevity contributes to under-specification rather than representing deliberate efficiency.

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

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

Despite having an output schema, the definition is too thin for a mutation tool with eight parameters and many siblings. It lacks usage conditions, identifier-selection guidance, and behavior after replying, so an agent has to infer most call semantics.

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

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

Schema coverage is only 50%, and the tool description adds no parameter-level meaning. Required 'threadId' and 'body' are left to be inferred, and the conditional relationship between identifier pairs (articleId/articleTitle, workspaceId/workspaceName) is only explained partially in the schema.

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

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

The description states a clear verb and resource: 'Reply' to an 'existing review thread'. This distinguishes the action from thread creation or resolution, but it does not explicitly differentiate from the sibling 'add_comment', leaving some 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?

There is no guidance on when to use this tool instead of add_comment, resolve_thread, or other siblings. The word 'existing' implies the target must already be created, but no alternatives or exclusions are stated.

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

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

The annotations already indicate this is not read-only, not idempotent, and not classified as destructive; the description adds useful guidance about ID provenance and that the thread must already exist. However, it does not disclose error behavior, side effects, permissions, or what happens when the thread is already resolved, so some behavioral context is still left implicit.

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 action and then states the most important invocation constraint. Every part earns its place, and there is no repetition of schema details.

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 state-changing tool with an output schema and high schema coverage, the description plus schema provide the essential invocation details. A small gap remains in workflow context: it does not explicitly position this tool relative to reply_to_thread or list_review_threads, but the existing text is sufficient for correct use in most cases.

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 high at 86%, so the schema already explains threadId, targetId, articleId, and workspaceId. The description reinforces the pairing of threadId and targetId and warns against commandId, which is helpful but does not add meaning beyond what the schema already states.

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

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

The description states a specific action ('Resolve an existing review thread') on a specific resource, which is immediately distinguishable from sibling tools like reply_to_thread, accept_suggestion, or list_review_threads. It also adds a critical disambiguation ('not commandId') that separates this operation from related review-thread commands.

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 invocation context: resolve an existing thread using the exact identifiers from add_comment, and explicitly warns against using commandId. It does not name alternative tools or give when-not-to-use conditions, but the intended workflow is clear enough for an agent to select this tool correctly.

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 indicate destructive=true and readOnly=false, but the description adds critical operational context: the permission scope ('Requires publishing:write') and the mandatory user confirmation step. These are not derivable from annotations and meaningfully shape how an agent should approach the call.

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

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

Two sentences with zero fluff. The core purpose is front-loaded, followed by parameter ergonomics and the critical confirmation requirement. Every clause earns its place 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 destructive, permission-gated tool with a required confirmation flag and an output schema available, the description covers the essential invocation requirements. It does not explain the result or side effects in prose, but the output schema likely covers that, so the description is sufficiently complete for an agent to call it correctly.

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

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

The schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The description's note about preferring natural names over internal IDs is already reflected in the schema descriptions, so it adds no new semantic value beyond a helpful summary of the intended usage pattern.

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

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

The description states a specific verb and resource ('Disable a Markdown Document public link') that clearly distinguishes it from siblings like publish_article and edit_article. The purpose is unambiguous and immediately actionable.

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 (unpublishing a document) but does not explicitly state when to use this tool over alternatives, nor does it mention exclusions or sibling tools. It gives invocation guidance (accepts natural names) but not selection guidance, so the agent must infer context.

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