Markdown by mdedit.ai

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

Goes beyond the annotations (destructiveHint=true, idempotentHint=true) by naming the concrete downstream effects: content changes may update an existing live public link or an enabled publication sync. That is real second-order impact disclosure an agent needs before mutating a published document. It does not, however, spell out what happens to the review thread or whether the action is reversible.

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, zero filler: effect first, side effects second, invocation prerequisite third. All information is front-loaded and each sentence earns its place.

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

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

For a destructive mutation with rich annotations and an output schema (so return values need no explanation), the description covers the effect, side effects, and ID sourcing. Minor gaps remain around permissions, thread state after acceptance, and idempotency/retry semantics, though the latter are partially covered by commandId's schema text.

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 baseline is 3, but the description adds provenance the schema cannot: it identifies suggestionId and targetId as values returned by add_suggestion or list_review_threads and stresses using the exact values. It says nothing about commandId, context, or the lookup-narrowing params, which the schema itself documents well.

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+resource ('apply an existing review suggestion to the document and mark it accepted') with the atomicity guarantee front-loaded. The add/reject/accept family of siblings is trivially distinguishable by the verb alone.

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 tells the agent to use the exact suggestionId and targetId returned by add_suggestion or list_review_threads, establishing the prerequisite and the source of the identifiers. It stops short of stating when NOT to use it (e.g. rejected/stale suggestions or the alternative reject_suggestion path).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety and retry profile is largely covered. The description's 'without directly changing document prose' is a useful clarification of mutation scope, but it partially restates destructiveHint=false, and adds no auth, rate-limit, or failure-mode detail.

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, front-loaded with the core action and scope, then the input flexibility, then the return contract. No filler or restated 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?

Output schema exists so return format need not be explained, yet the description still tells the agent which values to carry forward into follow-up calls, which is valuable chaining context for a 9-parameter tool. Minor gap: no note on anchor failure behavior or idempotent retry expectations beyond what commandId's schema text provides.

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 67% schema coverage, the schema handles most parameter documentation, but the description adds real routing guidance the schema does not: it tells the agent that natural workspace names and document titles are acceptable and that internal routing identifiers are optional. It also flags the anchor/body requirement implicitly via 'anchored ... comment'.

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+resource ('Add an anchored review comment') and immediately scopes it ('without directly changing document prose'), which cleanly separates it from siblings like add_suggestion, edit_article, and save_article_content. An agent can route to it without opening any schema.

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

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

The description names the downstream tools (reply_to_thread, resolve_thread) that consume the returned threadId/targetId, giving clear workflow context for when this tool belongs in a sequence. It stops short of stating explicit exclusions, e.g. when to prefer add_suggestion over a 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the suggestion is a pending proposal awaiting human accept/reject, and the response yields the two IDs needed to act on it. It adds no permission or failure-mode detail, so it is not a 5.

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, front-loaded with what the tool creates and followed by input conventions and return values. No filler or repetition of schema mechanics.

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 10-parameter mutation with an output schema, the description covers the important ground: artifact type, human-review workflow, flexible identifier input, and follow-up IDs. The main gap is that the anchor forms and the note field remain unexplained outside the schema.

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 60%, so the description must compensate, and it does for the routing parameters: it says natural workspace names/document titles are accepted and internal identifiers are optional, which clarifies articleTitle/workspaceName vs articleId/workspaceId/targetId. It does not explain the anchor's quote-vs-range alternatives or the note/replace fields.

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 (Add) and resource (an anchored replacement suggestion) plus the essential qualifier that a human must accept or reject it, which separates it from a direct edit_article or add_comment. It also names the downstream siblings (accept_suggestion/reject_suggestion), so an agent can place it in the review workflow without opening the schema.

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

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

Makes the workflow context explicit by stating the returned suggestionId/targetId are consumed by accept_suggestion or reject_suggestion, and tells the agent that natural workspace names and document titles are acceptable so it need not interrogate the user for internal IDs. It stops short of an explicit when-not-to-use rule versus add_comment or edit_article.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: the operation is asynchronous, a jobId is returned and must be polled, and it must never be shown to the user. It does not cover error or format-rejection behavior, so it falls short of exhaustive.

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: capability, invocation/privacy handling, and sibling routing. The important scope constraint 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 an async conversion tool with an output schema and full annotation coverage, the description supplies the workflow and routing context an agent needs. It stops short of describing supported-format limits or failure modes, but return values are already covered by the output schema.

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 all five parameters are documented structurally. The description adds only a little beyond that ('Pass the content directly; the document does not need to exist in mdedit') and says nothing about the 'context' or 'from' semantics. Baseline 3 is appropriate.

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

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

States a specific verb ('Convert') and resource (Markdown/HTML content into Word, PDF, HTML, LaTeX, EPUB), and distinguishes itself from the sibling start_article_export. An agent can tell exactly what this does without opening the schema.

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

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

Names the alternative explicitly ('To export a document already stored in mdedit, use start_article_export instead') and gives the routing condition. It also explains the follow-on step via get_conversion_status, so the full workflow is clear.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety/idempotency profile is covered. The description adds 'durable' and 'initial content', which is light context, but omits any auth/permission requirement or what happens to pre-existing content. With annotation coverage already strong, this is a modest addition.

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

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

Two sentences, front-loaded with the core action before the workspace-selection branch, with no filler. It is efficient, though the second sentence is dense and could be scannable rather than run-on.

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?

An output schema exists, so return values need not be explained, and annotations carry the mutation/idempotency profile. For a create tool with 8 params, the definition is broadly sufficient, though it never addresses permissions or the collaborative flag.

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 50%, so half the parameters (title, content, folderId, collaborative) are undocumented in both places. The description reinforces the workspace selection rule, but the schema's own workspaceId/workspaceName descriptions already cover that, so the marginal value is small. 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?

States a specific verb plus resource ('Create a Markdown Document') with the scope qualifier 'in an accessible workspace' and the notion of 'initial content'. This is clearly distinct from siblings like edit_article and save_article_content, but it never explicitly names or contrasts an alternative, 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 stated guidance ('Omit the workspace selector when the user has only one workspace, or pass workspaceName when they chose one by name') is really parameter-selection advice rather than when-to-use-this-tool-versus-a-sibling guidance. There is no statement about when to create versus edit or convert a document, which leafs usage implied.

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

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

Annotations declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the description doesn't need to repeat safety traits. It adds value by noting that edits can affect live public links or publication sync, which is important behavioral context. However, it omits critical details like what gets destroyed, whether auth/permissions are required, or how errors/conflicts are handled, leaving significant gaps for a destructive operation.

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

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

The description is two concise sentences that front-load the core action and scope. It is efficient but could be slightly more structured by separating behavioral constraints from usage hints.

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 (8 params, destructive, open-world) and the presence of an output schema, the description is somewhat complete but fails to address key behavioral aspects like permission requirements, error handling, or the implications of destructive edits on live links. It provides basic context but not enough for an agent to fully understand the operation's impact.

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 75%, so most parameters are documented. The description adds a bit by mentioning 'natural workspace names and document titles' and that internal routing identifiers are optional, which aligns with the schema's notes on articleId and workspaceName. But it doesn't clarify the 'operations' structure, 'commandId' usage, or 'ifContentHash', leaving some semantic 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?

States a specific verb ('Apply anchored edits') and resource ('Markdown Document' via title), and clarifies scope related to live public links and publication sync. It is fairly clear, though the phrase 'mdedit's authoritative ordinary or collaborative document service' is somewhat jargon-heavy and doesn't sharply differentiate from sibling 'save_article_content'.

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

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

The description implies usage for anchored edits but does not explicitly state when to choose this tool over alternatives like save_article_content or add_suggestion, nor does it outline exclusions or prerequisites beyond mentioning link/sync updates.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for adding behavior beyond them: it returns a download resource link on completion and deliberately withholds the internal job identifier. This gives the agent real expectations about the response's shape and security posture.

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, front-loaded with the action and its prerequisite, then the return behavior. No filler; every clause carries 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?

For a two-parameter status-check tool with annotations covering safety and an output schema covering return values, the description supplies the prerequisite, the completion signal, and the withholding behavior. Only labels remain undocumented.

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

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

Schema coverage is 50% – the 'context' parameter is documented, but 'jobId' has no schema description. The description partially compensates by linking jobId to an export created by start_article_export, but never clarifies its format or source, and the phrase about not exposing the internal job identifier could confuse which identifier is which.

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 resource ('an export started by start_article_export'), tying it directly to the sibling that initiates the workflow. An agent can distinguish it from start_article_export, though it doesn't contrast with other status-style siblings like get_conversion_status or get_publish_status.

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?

Usage context is implied by 'started by start_article_export', which establishes the prerequisite, but there is no guidance on polling cadence, terminal states, or when to prefer this over the other status tools in the sibling set. Adequate but with clear gaps.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two useful behavioral facts — a download resource link is produced on completion, and the internal job identifier is not exposed — but says nothing about the pending/failed states an agent polling this tool must handle.

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 front-loaded sentence with zero filler; the completion behavior is stated immediately after the core purpose. 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 two-parameter polling tool the description covers purpose and completion outcome, and an output schema exists so return-value details need not be repeated. The only real gap is the absence of guidance on intermediate states (pending, failed) and polling behavior.

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

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

Schema coverage is 50%: the `context` parameter is documented in the schema, but `jobId` carries only a minLength constraint. The description partially compensates by implying the jobId originates from convert_document, but it adds no format, lifetime, or validity detail beyond what the schema already implies.

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+resource ('Check a conversion') and anchors it to the sibling that creates the work: 'started by convert_document'. That is enough to separate it from the generic article tooling, though it does not explicitly distinguish itself from the other status-check siblings such as get_article_export_status or get_publish_status.

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?

Usage is implied by the prerequisite 'started by convert_document' — an agent can infer it should be called after starting a conversion. However, there is no guidance on polling cadence, when to stop, or what to do if the conversion fails, and no explicit when-not-to-use statement.

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, destructiveHint=false and closed-world access, so the safety profile is fully covered structurally. The description adds only that lookup accepts human-friendly names and that internal IDs are optional, which is routing context rather than behavior. 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, no filler, with the core action front-loaded in the first sentence and the identifier-flexibility note second. Every clause carries weight.

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 a full output schema and 100% parameter coverage, return values and argument formats are already handled. The description is adequate for a read-only lookup, though it leaves the meaning of 'present' (live session vs. membership) and empty-result behavior unstated.

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 echoes the schema's own guidance ('accepts natural workspace names and document titles; internal routing identifiers are optional') but adds no syntax, format, or precedence detail beyond it, and never mentions the required 'context' parameter.

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

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

States a specific verb and resource: 'List the people and agents currently present in a collaborative document.' The resource (presence) is unique among the siblings (comments, threads, articles, exports), so an agent can separate it without opening a schema. It stops short of explicitly naming a sibling it displaces.

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?

Usage is only implied by the purpose: you call this when you need to know who is currently in a document. There is no statement of when-not to use it, no prerequisites, and no pointer to a related tool such as read_article or list_review_threads.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that the response surfaces a stable public-link URL plus publication state, which is real but modest added context beyond the annotations and schema.

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

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

Two sentences, front-loaded with the core purpose and outcome followed by input-form guidance. No filler or hedging; the only minor redundancy is the second sentence echoing what the schema already states.

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

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

This is a simple read-only status lookup: annotations cover safety, all five parameters are fully documented in the schema, and an output schema exists so return values need no prose explanation. The only gap is any explicit routing against the publish/unpublish siblings, which is not strictly required to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the guidance to omit articleId when referring by title and that workspace narrowing is optional. The description's sentence about natural names and optional internal identifiers essentially restates that, so the baseline 3 applies.

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

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

States a specific verb and resource (get the publish status/publication state of a Markdown Document) and additionally names the payload (stable public-link URL). An agent can distinguish it from the mutating siblings publish_article and unpublish_article, though the description never explicitly contrasts them.

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 tells the agent it can pass natural workspace names and titles with internal routing identifiers optional, which is useful invocation context, but it gives no explicit when-to-use/when-not guidance and never names an alternative (e.g. read_article or the publish/unpublish siblings). Usage is only implied.

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, non-destructive, so the safety bar is low. The description adds real behavioral context: default scope is all authorized workspaces, results are grouped by workspace, output is bounded, and cursor must be reused with the same workspace selection and query.

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?

Front-loaded with the default scope and the key exclusion (no full content) before the optional-parameter guidance. The default-scope statement is restated twice ('across all authorized workspaces by default' / 'No workspace choice is needed'), a small redundancy but not enough to obscure the content.

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

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

An output schema exists so return values need not be described, and the description covers scope, grouping, search, and pagination. The only omission is the limit/bound size, which the schema's maximum:50 does supply.

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 67% (limit and query lack descriptions), yet the description explains query as title search, nextCursor as pagination with matched selection/query, and the workspace params as narrowing filters. Only limit is left unexplained, so it meaningfully compensates for the coverage 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?

States a specific verb (list/search) and resource (Markdown Documents), plus two distinguishing scope facts: results are grouped by workspace and full content is NOT returned. This lets an agent separate it from read_article without opening either schema.

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

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

Gives clear context: workspace params are optional and only for narrowing, and query/nextCursor drive search and pagination. It does not name a specific sibling alternative (e.g. 'use read_article for content'), so it stops short of full when/when-not 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, and destructiveHint=false, so the safety profile is covered. The description adds that the tool accepts natural workspace names and titles and that internal IDs are optional, which is useful context, but it doesn't mention pagination, result limits, or what thread states are returned – gaps given the lack of annotation detail on those.

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

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

Two sentences, both front-loaded with the core action and routing behavior; 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?

With an output schema present, the description needn't explain return values. For a read-only list tool with annotations covering safety, the description covers the main routing nuance (natural names vs. IDs). Minor gap: no mention of filtering by status or what 'thread' statuses exist, though the output schema likely covers this.

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 71%, so several parameters (articleTitle, workspaceName, articleId, workspaceId) are already documented in the schema. The description reinforces that titles and names are accepted and that internal identifiers are optional, but it adds little beyond what the schema states and does not cover the undocumented 'status' and 'targetId' 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 states a specific verb (List) and resource (review comments, highlights, suggestions for a document), which distinguishes it from write-oriented siblings like add_comment and resolve_thread. It does not name a specific sibling alternative, so it falls short of 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?

Usage is implied by 'List ... for a document' – an agent can infer this is the read path for review threads. However, the description gives no explicit when-to-use vs. when-not-to-use guidance or alternatives, leaving the agent to infer from sibling names.

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 non-destructive behavior, so the safety profile is covered. The description adds genuinely new context: document content is excluded from the result and a 'setup' element may require a user-approval step, which is behavior an agent cannot infer from 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, no filler, and the core action is front-loaded ahead of the conditional workflow instruction. Every clause carries information the agent needs.

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, return values need not be explained, and the description still flags the notable 'setup' branch. Combined with full param coverage and rich annotations, an agent has what it needs, though the relationship to document-creation tools could be spelled out more.

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 the single 'context' parameter is fully documented in the schema, including the privacy warning. The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the mdedit workspaces') and scopes it with 'available to this app without returning document content.' No sibling tool lists workspaces, so there is nothing to differentiate against, but the scope is precise 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?

Gives a clear conditional workflow: if setup is returned, surface its link and ask the user to approve access before creating a document, which implicitly positions this as a prerequisite call. It does not name any alternative tool or state when not to call it, so it stops short of full routing 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 destructive/openWorld/idempotent, but the description adds genuinely new behavioral facts: the required scope (publishing:write), the need for explicit user confirmation, and the key trait that later durable edits update a live link at the same URL. This is meaningful disclosure beyond the structured hints.

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?

Front-loads purpose, then mode semantics, then permission requirements, with no filler. Every sentence carries information, though the mode explanation partly restates the mode schema description, making it slightly denser than necessary.

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 10-parameter mutation with a nested seoMetadata object and an output schema, the description covers the critical behavioral and permission surface well. Return values are handled by the output schema, so the remaining gaps are only the uncovered customSlug and seoMetadata 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 80%, so the baseline is 3, and the description adds real value: it explains that workspace names and document titles are accepted with internal routing identifiers optional, mapping directly onto articleTitle/articleId/workspaceName behavior. It omits customSlug and the seoMetadata object entirely, so not all uncovered parameters are 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?

States a specific verb+resource ('Publish or update a Markdown Document at a public mded.it link') and specifies the artifact type and target surface. It is clearly distinct from unpublish_article and get_publish_status in intent, but never names or contrasts with those siblings, so it sits just below the top bar.

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?

Gives real selection guidance for the mode parameter ('New links default to live', 'Choose snapshot for a frozen artifact', 'Existing links keep their stored mode unless mode is supplied') and states prerequisites (publishing:write, explicit user confirmation). It does not, however, address when to reach for publish vs unpublish or check status.

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 non-destructive, so the safety profile is covered. The description adds that the content returned is the currently saved revision (not a rendered or draft view), which is genuinely useful context, but it says nothing about authorization scope or lookup failure behavior when a title is ambiguous.

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 short sentences with no filler; the core action is front-loaded and the identifier guidance follows. Every clause carries information the agent can act on.

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?

An output schema exists, so return values need not be described, and the annotation set covers the safety profile. The remaining gap is minor: nothing explains how lookups resolve when a title matches multiple documents, which the schema hints at but does not settle.

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 every parameter is already documented, including the preference for articleTitle over articleId and the optional narrowing role of workspaceId/workspaceName. The description restates that preference in prose but adds no syntax, format, or ambiguity-resolution detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Read the current saved Markdown content and metadata for a document'), and the word 'saved' implicitly separates it from render_article, which produces a rendered view. It does not name any sibling explicitly, so the differentiation is inferable rather than stated.

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 second sentence gives real invocation guidance on how to identify the document (natural workspace names and titles preferred, internal identifiers optional), which is implied usage rather than explicit when-to-use. It never says when to choose this over list_articles or render_article, so the routing guidance is only partial.

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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false, idempotentHint=false). The description adds a genuinely useful privacy constraint not present in annotations — no document content, identifiers, prose, or URLs — but says nothing about when events fire, whether calls are batched, or what a successful record returns.

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 short sentences with no filler, and the constraint is stated before elaboration. Efficiency is good, though the first sentence spends its slot on positioning ('component-only privacy-safe') rather than a concrete statement of what the tool does.

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 7-parameter tool with only 2 required fields, 14% schema coverage, and no usage guidance, the description is too thin. An output schema exists so return values need not be explained, but the agent still lacks guidance on required inputs and when to emit which event.

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 14% — just the 'context' string field. The description adds no field-level meaning beyond reinforcing what not to put in the free-text field; it does not explain the relationship between `event`, `focus`, `action`, `format`, and `status`, or which combinations are valid. With low coverage, the description should compensate and does not.

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

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

The description labels the tool as 'operational telemetry' but never states the verb+resource plainly (i.e., records an app event); it leans on the title to convey that. It does not differentiate from any sibling tool, though none of the listed siblings are telemetry-related. The purpose is inferable but not stated.

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 call this tool, which event values correspond to which user flows, or what to do instead. The only direction given is negative ('never accepts...'), which is a constraint rather than usage 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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by confirming the mutation does not alter the document body, which explains why the destructive hint is false and reassures 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?

Two sentences, no filler, and the core effect ('without changing the document') is front-loaded in the first sentence with the parameter provenance following. 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?

With an output schema present, return values need not be explained, and the description covers the essential effect and identifier sourcing for an 8-parameter tool. It could have noted that the mutation is idempotent per commandId, but the annotations and schema already carry 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?

Schema coverage is 75%, so the schema documents most parameters including commandId retry semantics and the article/workspace narrowing options. The description adds provenance meaning for suggestionId and targetId but says nothing about the required 'context' or commandId reuse beyond what the schema already states, so it only marginally exceeds the baseline.

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

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

States a specific verb (reject) and resource (existing review suggestion) and adds the scoping constraint 'without changing the document', which cleanly separates it from accept_suggestion and any edit/article mutation sibling. An agent can identify the operation and its effect on the document without opening the schema.

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

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

The second sentence tells the agent where to obtain the required identifiers ('returned by add_suggestion or list_review_threads'), which is useful provenance guidance, but it never states when to choose reject over accept or what a valid rejection precondition is. Usage is implied rather than spelled out.

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, non-destructive, and closed-world, so safety is covered. The description adds the useful detail that identifiers are optional and natural names are accepted, but it never explains what 'focus' does or whether export/publish focuses trigger side effects, which sits uneasily beside readOnlyHint.

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 front-loaded sentences: the action first, then the identifier convention and usage triggers. The trailing verb list is somewhat padded but not wasteful enough to hurt readability.

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, rich annotations, and high parameter coverage, the description does not need to cover return values. However, for a six-parameter tool with a behavior-changing 'focus' enum, it should at least route the agent away from read_article and clarify that 'focus' selects export/publish/review modes.

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 83%, so the schema largely documents the six parameters. The description only reinforces the title/name-vs-ID preference already stated in the schema; it adds nothing about the 'focus' enum or the required 'context' argument. 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 gives a clear verb + resource: 'Open the current saved document in the mdedit reader,' plus the accepted reference style (natural names/titles over internal IDs). It never distinguishes itself from the close sibling read_article, so an agent cannot tell which to pick from the description alone.

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 supplies trigger contexts ('after creation or updates') and a list of request types (open, read, show, preview, export, publish, review). But several of those triggers overlap directly with siblings like read_article, start_article_export, and publish_article, and there is no when-not-to-use or sibling routing, so the guidance is implied rather than decisive.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, which cover the safety profile. The description adds nothing on top — no mention of what a reply appends, whether participants are notified, or what the idempotency key protects against — so it contributes no behavioral context beyond structured data. 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?

The single sentence is front-loaded and free of filler, which is good, but for a 9-parameter mutation tool this level of brevity reads as under-specification rather than tight writing.

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?

An output schema exists, so return values need not be explained. Still, for a non-destructive but non-idempotent-looking mutation in a dense sibling set (accept/reject suggestion, add_comment, resolve_thread), the description omits all context an agent needs to select it correctly, leaving a significant gap.

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

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

With 9 parameters and only 67% schema description coverage, the description is the natural place to clarify the required threadId and body fields plus the document-lookup fields (articleId, articleTitle, workspaceId, workspaceName). It supplies none of that, leaving the two required params entirely undocumented anywhere.

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 (reply to a thread), and the word 'existing' implies the thread must already exist. However, it essentially restates the tool name and title with no differentiation from siblings like add_comment or resolve_thread, so an agent gains almost nothing beyond what the identifier already conveys.

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 versus add_comment (which may also post text) or resolve_thread, nor on prerequisites such as the thread needing to be unresolved. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety/idempotency profile is covered structurally. The description adds one useful behavioral nuance — that threadId/targetId (not commandId) carry thread identity — but says nothing about who may resolve a thread, whether it can be reopened, or what happens on a non-existent thread.

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

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

A single sentence with the action front-loaded and the parameter constraint immediately after. No filler, no 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 8 fully documented parameters, an output schema covering the return shape, and annotations covering mutability and idempotency, the description is nearly sufficient. The one gap is any statement of the effect of resolving (thread state change, permissions), but the surrounding structured data compensates well.

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 every parameter is already documented, including the threadId/targetId vs commandId distinction and the commandId retry semantics. The description restates that guidance rather than extending it, 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?

States a specific verb and resource: 'Resolve an existing review thread.' An agent immediately knows this closes out a thread as opposed to replying to it (reply_to_thread) or acting on a suggestion. However, it does not explicitly contrast itself with any sibling tool, so it lands at 4 rather than 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 a prerequisite workflow by requiring 'the exact threadId and targetId returned by add_comment,' which tells the agent this must follow a prior comment creation. It gives no explicit when-to-use vs reply_to_thread/list_review_threads, nor any when-not condition.

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 a non-read-only, destructive, idempotent, open-world write, so the safety profile is covered. The description adds genuinely new behavior: the optimistic-concurrency contract (mismatched baseContentHash writes nothing and returns latest content for reconciliation) and the side effect on live public links and enabled publication sync. It does not mention required permissions or auth, keeping it short of a 5.

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 the key scoping constraint ('Component-only') front-loaded and no filler. The middle sentence on public-link/publication-sync side effects is relevant but is the one piece that could be tightened.

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, idempotent write tool with an output schema present, the description supplies the failure mode, the concurrency contract, and the downstream side effects, which is what an agent needs to call it safely. Auth/permission requirements are the only meaningful omission.

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% — commandId and context are documented, but content, articleId, workspaceId, and baseContentHash are bare. The description compensates for baseContentHash ('the content hash the editor last loaded'), which is the highest-risk parameter, but adds nothing for content, articleId, or workspaceId, so the coverage gap is only partially filled.

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 (saves the full text buffer as one minimal anchored edit) and scopes it with 'Component-only', which tells the agent this is not the general-purpose edit path used by siblings like edit_article or create_article. An agent can distinguish it from the other write tools without opening the schema.

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

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

'Component-only' implies the calling context (embedded mdedit editor) and thereby rules out most general use, and the description states the precondition (requires the last-loaded content hash). However, it never names an alternative tool for non-component edits and gives no explicit when-not-to-use guidance, so usage is only implied.

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?

Adds real context beyond annotations: the job is asynchronous, returns an opaque jobId, and that ID should never be surfaced to the user. Annotations already cover safety (readOnly, non-destructive), so this addition of job-lifecycle and disclosure behavior is valuable.

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: action first, then input guidance, then the mandatory polling step and ID-handling rule. No wasted words.

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

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

Covers the essential call pattern, required polling, and ID confidentiality for a tool with an output schema. Minor gaps: no mention of export formats or whether prior exports are cancelled, but the core behavior is complete.

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

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

Schema coverage is 83%, so the schema already documents format, context, articleId, workspaceId, articleTitle, and workspaceName. The description only reinforces the natural-name vs identifier preference, which the schema already states, so it adds little beyond the baseline.

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

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

States a specific verb ('Start an asynchronous export') and resource ('current saved document'), with the async nature and handoff to get_article_export_status made explicit. Clearly distinct from get_article_export_status and convert_document.

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?

Explains the polling workflow via get_article_export_status and states that natural names are accepted over internal identifiers, but does not cover when to choose this over direct render_article or convert_document.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: the required publishing:write scope and the mandatory user-confirmation gate tied to confirmUnpublish. It still does not say what happens to the existing link/content after disabling.

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 the action front-loaded, followed by argument guidance and then preconditions. No filler or repetition; every clause carries 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?

With an output schema present, return values need not be explained, and annotations cover the mutation/intent profile. The description completes the picture with auth scope, confirmation flow, and argument flexibility, leaving only the post-unpublish effect (link invalidation consequences) unstated.

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 restates the naming model (natural titles/workspace names accepted, internal IDs optional) that the individual schema fields already document, so it adds little meaning the schema does not already carry.

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

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

The description gives a concrete verb and resource: 'Disable a Markdown Document public link', which is unmistakably the inverse of the sibling publish_article. It is clear on its own, though it never names the counterpart tool explicitly, so the agent must infer the pairing from the tool name rather than the text.

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

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

It supplies invocation context ('Accepts natural workspace names and document titles; internal routing identifiers are optional') and a precondition ('Requires ... explicit user confirmation'), which implies when the tool is callable. It does not, however, state when to choose this over publish_article or get_publish_status, nor any exclusion conditions.

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