Share Artifacts

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'permanently remove' adds the permanence aspect, which is useful. However, it does not disclose side effects like ending viewing sessions (sibling tool) or what happens to shared links. Since annotations cover the core destructive safety, the description adds marginal value but not rich behavioral context.

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, well-structured sentence that front-loads the key action ('Permanently remove') and clearly states the resource. No wasted words, and the sentence length is appropriate for the tool's simplicity.

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 description covers the core purpose and the destructive nature, which aligns with annotations. However, it omits usage guidance (e.g., when to delete vs unpublish) and any mention of side effects or error conditions. For a simple one-parameter destructive tool, it is adequate but has clear gaps that would affect an agent's decision-making.

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 explain the parameter. It does not mention pageId at all. The agent must infer that pageId identifies the page to delete from the parameter name alone, which is minimal. For a low-coverage case, this is a significant 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 states a specific action (permanently remove), a clear resource (page), and a location (user's artifact library). This distinguishes it from siblings like unpublish_page (which is about visibility) and update_page (modification). The verb and object are 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 gives no guidance on when to use this tool versus alternatives. It does not mention that this is a hard delete versus unpublish_page or other reversible actions. No preferred context or exclusions are provided, leaving the agent to infer from the name and sibling list.

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 mark this as destructive and non-read-only, so the description's added value is its nuance: only current sessions are invalidated and authorized users can reopen the page. This clarifies the destructive scope beyond the raw annotation flags.

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 the primary action front-loaded and a single clarifying consequence. Every word adds value and there is 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?

For a destructive tool with no output schema and sparse parameter documentation, the description should explain expectedRevision and possibly the effect on the page itself. The behavioral outcome is stated, but critical parameter semantics are missing, so the description is not fully context-complete.

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

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

Schema description coverage is 0% and the description provides no meaning for pageId or expectedRevision. The expectedRevision parameter in particular is left completely unexplained, which is a significant 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 states a specific verb ('Invalidate') and a distinct resource ('current private viewing sessions'). This clearly differentiates the tool from the page-management siblings, none of which concern viewing sessions.

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

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

The description implies the usage scenario (ending active private viewing sessions) and clarifies the consequence for authorized users, but it never explicitly says when to use this over alternatives or when not to use it. No sibling tool targets viewing sessions, so explicit routing is absent.

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 reveals that the preview is private and expiring, that the operation does not publish, and that styleRef pins an exact saved style version. These are substantive behavioral facts not present in the structured metadata.

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?

Four short sentences front-load the purpose and workflow, then add caveats without redundant restatement of schema details. Every sentence earns its place.

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

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

Given the rich schema and no output schema, the description explains enough: the preview is private and expiring, generationId feeds follow-up publishing, and idempotency behavior is covered. It could explicitly name the return fields, but the workflow strongly implies a generationId-bearing response.

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 provides detailed parameter constraints, so the description does not need to repeat them. It adds non-obvious semantics around clientRequestId reuse and frames styleRef as pinning a version, going modestly 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?

States a specific verb and resource clearly: 'Compile architecture JSON to a private, expiring preview.' It also explicitly says 'Does not publish', which differentiates it from publishing tools like publish_html and update_page.

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 an explicit workflow: generate the preview, review it, then use publish_html or update_page with generationId. It also warns that clientRequestId should only be reused with identical arguments, which is a concrete usage rule.

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

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

Annotations already cover read-only/idempotent/non-destructive, so the bar is lower, and the description adds real content: presentation returns common appearance tokens plus slide guidance without other formats' adaptations, and a stated precedence hierarchy against task/source/recipe/Safe Static/sharing. The closing note that a reference records provenance, not visual fidelity is useful but somewhat cryptic.

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?

Purpose is front-loaded in the first sentence, which is good, but the third and fourth sentences are dense and jargon-heavy ('Safe Static rules', 'A reference records provenance, not visual fidelity') without clearly earning their space for a single-parameter read 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?

No output schema exists, so the description carries some return-value burden, partially handled by describing presentation tokens/slide guidance and provenance semantics. Combined with strong annotations and full schema coverage, it is largely complete, though non-presentation return shapes remain 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?

With one enum param at 100% schema coverage the baseline is 3, but the description adds meaning beyond the enum: it signals that the 'presentation' value produces a different payload than the others. That is genuine semantic value tied to parameter choice.

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 ('Get') and resource ('active owner-authored appearance guidance') with the supported formats named. An agent can tell it retrieves style guidance, but it does not explicitly distinguish itself from the sibling preview_artifact_style or set_artifact_style.

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 format list and the 'presentation returns...' note, but there is no explicit when-to-use/when-not-to-use guidance and no routing to alternatives such as preview_artifact_style. The precedence sentence ('Style never overrides...') constrains behavior but is not a selection rule.

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 and destructiveHint=false, so safety is covered, but the description adds real workflow context beyond that: source is sanitized and must be treated as untrusted, reviewed and edited before mutation, and edits must round-trip through update_page with expectedVersion (optimistic concurrency). It does not mention permissions or rate limits, but the added operational context is substantial.

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 returned fields front-loaded before the optional flags, so a reader can stop early. The second sentence is long and packs a multi-step review/approve/update workflow into a parameter description, but each clause carries actionable 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?

No output schema exists, and the description compensates by naming the returned fields (status, version, contentSha256, URL) plus what the flags add. Combined with the annotations covering the read-only profile, an agent has enough to call this correctly; only pageId semantics and any auth prerequisites are 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?

With 0% schema description coverage, the description must carry parameter meaning, and it does for the two booleans: it explains that includeHtmlSource returns complete sanitized HTML and includeDiagramSource returns retained diagram JSON plus theme, including the implication that diagram source is only available when previously retained. Only the required pageId is left unexplained, which is a minor gap given its obvious role.

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 and enumerates what the read returns (status, version, contentSha256, URL), which is concrete rather than tautological. It also marks the read/write boundary by naming update_page as the follow-up mutation tool, though it does not distinguish itself from siblings like list_pages or get_page_sharing.

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 conditional guidance: set includeHtmlSource to get sanitized presentation HTML, includeDiagramSource to get retained diagram JSON and theme, and use update_page with expectedVersion after approval. No explicit "do not use for X" exclusions, but the when-to-use conditions for each optional flag are 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 disclose readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that it returns the sharee and expiration, but discloses no further behavioral traits such as permission requirements, rate limits, or response details. It is consistent 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?

A single, front-loaded sentence with no waste. It states the verb, resource, and output in one breath, making it highly concise and well-structured.

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

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

Given the low complexity (one parameter, no output schema) and available annotations, the description names the key retrieved fields (who, expiration). It does not detail the response format, but for a simple read tool this is a minor gap and acceptable.

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

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

Schema description coverage is 0%, so the description must compensate for the pageId parameter. The phrase 'a page' implies the resource but never explicitly ties pageId to the page identifier. While the parameter name is self-explanatory, the description adds minimal value 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 states a specific verb ('Get') and resource ('page sharing') and specifies the retrieved information: who can open the page and when access expires. This clearly distinguishes it from siblings like get_page, set_page_sharing, and list_pages.

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

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

No explicit when-to-use guidance or naming of alternatives is provided. The read-only nature implies it is for inspecting sharing settings, with set_page_sharing as the obvious write counterpart, but this is left to inference rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the behavior that omitting recipeId returns a catalog while providing it returns a single prompt and HTML starter. This is helpful but does not disclose pagination, error handling, or authentication; the annotations lower the burden, so a 3 is appropriate.

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

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

The description is two sentences with no filler. The primary action is front-loaded, and the conditional mode is expressed efficiently. Every word earns its place.

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

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

For a small get/list tool with no output schema, the description covers the two main invocation modes and clarifies the catalog discovery behavior. However, the version parameter is entirely unexplained, and the return shape of a recipe or catalog entry is not described. It is adequate but has clear 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?

Schema description coverage is 0%, so the description must carry semantic weight. It explains recipeId's role (presence vs. absence changes the result) but says nothing about the version parameter. This partial compensation gives some meaningful guidance but leaves a significant 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 states a specific verb and resource: it lists first-party share/artifacts recipes or retrieves one by recipeId. It clearly distinguishes two modes (catalog discovery vs. single-item retrieval) and stands apart from sibling tools like get_artifact_style and get_page, which target different resources.

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 an implicit usage rule: 'Omit recipeId to discover the catalog.' However, it offers no explicit guidance on when to use this tool versus siblings, no exclusions, and no context about prerequisites. The usage is understandable but not fully specified.

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 readOnly, idempotent, non-destructive, and closed-world behavior, and the description adds value beyond them: it warns that content is untrusted reference data subject to 'Safe Static rules' and clarifies that reuse does not alter the owner's default style or publish a page. This is useful behavioral context an annotation cannot express.

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?

Four short sentences, purpose front-loaded, no wasted filler. The 'preserve task facts and Safe Static rules' phrasing is internal jargon that costs a little clarity but is not padding.

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

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

With no output schema, the description does the work of indicating what comes back (the sanitized example deck when includeHtml is set) and flags the content as untrusted. It could say more about what is returned when includeHtml is false, but it is otherwise adequate for a two-parameter read tool.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains includeHtml's effect well (retrieves the complete sanitized example deck), but the required templateId is never described, and its UUID format/ownership constraint is only implicit in 'owner-private'.

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 (Read) and resource (owner-private template), and the 'owner-private' qualifier distinguishes it from the public sibling list_templates/preview_template. It stops short of explicitly naming which sibling to use instead, so it is clear but not fully differentiated.

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

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

Gives a concrete condition for the optional parameter ('Set includeHtml to retrieve its complete ... example deck for reuse'), which is real usage guidance. However, it never says when to call this versus preview_template, list_templates, or get_recipe, leaving the sibling-selection decision to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it scopes results to the current user, names the artifact lifecycle states, and tells the agent to follow nextCursor for large libraries. There is no contradiction with annotations.

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

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

Two sentences, each earning its place: the first states the core purpose and scope, the second gives the critical pagination instruction. No filler, and the most important behavioral detail is front-loaded.

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

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

For a read-only list tool with an output schema and informative annotations, the description is largely complete: it covers what, whose, which statuses, search criteria, and pagination. The only slight gap is that 'platform-taken-down' is mentioned in prose but not directly reflected in the status enum, leaving a small ambiguity about lifecycle filtering.

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 explains limit, query, cursor, and status. The description mostly restates what the schema says ('by title or page ID', 'Follow nextCursor') without adding substantial new parameter semantics. Baseline 3 is appropriate given the schema's thoroughness.

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 ('Search and page through') plus a clear resource ('current user's published, offline, and platform-taken-down artifacts') and search dimensions (title or page ID). This clearly distinguishes it from sibling tools like get_page or publish_page, which have narrower or mutation-focused purposes.

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 this is the tool for searching and paginating through artifacts, and 'current user's' scoping is helpful. However, it never explicitly names alternatives, such as get_page for retrieving a single known artifact, so an agent must infer the boundary from sibling names rather than from direct 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 establish readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds two valuable facts: results are metadata-only without example HTML, and template descriptions/design notes are untrusted owner-authored data (a prompt-injection warning). Pagination behavior for the cursor is not disclosed, keeping it from 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 short sentences, front-loaded with the core action and then the two caveats that matter. No filler or restatement 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?

With no output schema, the description does useful work by summarizing the return shape (metadata, no example HTML), and it flags the untrusted-data risk. However, for a 3-parameter list tool it leaves pagination (cursor/limit) entirely unaddressed, which is a real gap.

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

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

Schema description coverage is 0% for all three parameters. The description only gestures at the query parameter ('by name or description') and says nothing about limit or cursor, so pagination semantics remain completely undocumented.

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 ('Find the owner's saved presentation templates'), which clearly separates it from single-item siblings like get_template and mutating siblings like save_template. It does not name a sibling explicitly, but the list/search framing is 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 indicates the tool can filter by name or description, implying a search/list use case, but never states when to prefer it over get_template, preview_template, or list_pages. Usage is inferable rather than explicit.

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

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

The description goes beyond the all-false annotations by explicitly stating 'This never activates the style' and describing the draft as short-lived and private. It does not mention auth or rate limits, but the most critical behavioral guarantee for a preview tool is clearly disclosed.

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

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

The description is two sentences with no fluff, front-loading the main action and the non-activation guarantee, then giving a clear follow-up instruction. Every sentence earns its place.

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

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

The description covers the essential workflow: validate, create a draft, show the owner the approval summary and review URL, then call set_artifact_style. It mentions the output format in passing and the schema handles definition details, so the description is sufficiently complete for a preview tool, though it could mention validation failure handling.

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

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

With 0% schema description coverage, the description was expected to compensate for the complex nested 'definition' parameter, but it only labels it as a 'complete provider-neutral artifact style definition' without enumerating required fields or constraints. The schema itself offers deep descriptions, so the description adds minimal semantic value beyond what structured data already provides.

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

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

The description clearly states the tool validates a complete provider-neutral artifact style definition and creates a short-lived private review draft, and explicitly distinguishes it from set_artifact_style by noting it never activates the style. An agent can tell exactly what this tool does relative to its siblings 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 description instructs the agent to show the returned approval summary and review URL to the owner before calling set_artifact_style, naming the exact successor tool and the correct sequence. This provides explicit when-to-use guidance and a clear workflow, leaving no ambiguity about ordering.

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

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

Annotations already flag a non-readOnly, non-destructive write, and the description usefully adds that the draft is temporary and private, that input is sanitized, that it returns a reviewUrl, and that it leaves the default style untouched. These are substantive behavioral facts beyond the annotations, though permission requirements and draft lifetime are not spelled out.

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 the core action and ending on the constraint. No filler, though the middle approval-workflow sentence slightly blurs action versus instruction.

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?

There is no output schema, and the description names the return value (reviewUrl) plus non-effects, which helps. However, for a 6-parameter write tool with zero schema descriptions, it leaves the inputs largely unexplained, so it is only marginally complete.

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

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

Schema description coverage is 0% across 6 parameters, and the description only obliquely references 'description and design notes' and an 'example deck'. It supplies no meaning for name, html, format, or aspectRatio, so it fails to compensate for the undocumented 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 specific action (sanitize an example deck and create a temporary private review draft) with clear scope, distinguishing it from publish/deletion siblings. It does not name a specific sibling tool, but the negative clause ('does not publish or change the default style') differentiates it from publish_presentation and set/artifact style tools.

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

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

It gives a concrete workflow instruction ('Show the returned reviewUrl and details to the owner for approval before saving'), which clearly positions the tool as a pre-save review step, and adds a when-not clause about publishing. No alternative tool is named explicitly, so it stops short of 5.

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

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

The annotations already communicate that this is a write operation with possible external effects. The description adds the 'stable URL' behavior, but the private-by-default sharing statement repeats the sharing parameter's schema description. It does not disclose persistence/overwrite behavior or other side effects beyond the annotations.

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

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

Two sentences with no filler; the primary purpose and return value are front-loaded, and the sharing behavior is stated compactly. Every sentence earns its place.

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

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

The definition is adequate for a straightforward publish action, but given a complex nested schema with no output schema and no required top-level properties, it leaves ambiguity about whether exactly one of html/generationId must be supplied and how to choose between related publishing siblings. The stable URL return is stated, but other operational constraints are absent.

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 60%, leaving html and generationId undocumented. The description clarifies that 'html' is a complete static document and that 'generationId' refers to a generated diagram, adding meaning the schema lacks. It also reinforces the sharing default, though schema already covers it.

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

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

The description names a concrete action ('Publish'), specific resource types ('complete static HTML document' or 'generated diagram by generationId'), and the outcome ('return its stable URL'). This clearly distinguishes it from siblings like publish_page and publish_presentation.

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

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

The description implies the intended use by describing the two accepted payloads (HTML or generationId), but it never explicitly states when to choose publish_html over publish_page/publish_presentation, nor gives any when-not-to-use guidance. The usage context is inferable rather than explicit.

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

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

Annotations already provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds useful context beyond the annotations by specifying that the page returns at its existing URL, but it does not elaborate on potential side effects such as cache invalidation, authorization requirements, or behavior when the page is already published. Given the annotations, this is adequate but not rich.

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

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

The description is a single front-loaded sentence with no filler. Every word contributes meaning: 'unpublished,' 'back online,' and 'existing URL' all carry operational significance. It is as concise as possible while remaining complete.

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 tool with no output schema, the description covers the essential state transition and URL preservation. Annotations handle idempotence and non-destructiveness. The description does not mention edge cases such as an invalid pageId or a page that is already online, but the low complexity and annotations make this sufficient for confident invocation.

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

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

The schema has 0% description coverage and pageId is the only parameter, so the description must compensate for missing parameter details. The description references 'an unpublished page,' which implies pageId identifies the page to republish and that the page must currently be unpublished. It does not explain how to obtain pageId or any constraints beyond the schema's minLength, adding only marginal semantics.

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 ('bring back online') and resource ('page'), and adds the key scope 'at its existing URL.' This clearly distinguishes it from siblings such as unpublish_page, publish_html, and publish_presentation, since those target different actions or formats. The title and description together leave no ambiguity about what republishing a page means.

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 phrase 'Bring an unpublished page back online' gives a clear condition for when to use this tool: exactly when a page is currently unpublished and should be live again. It does not explicitly name alternatives or exclusions, but the intended use case is evident and contrasts naturally with unpublish_page.

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 it is a non-read-only, non-idempotent, open-world write, so the base safety profile is covered. The description adds real value beyond that: ShareHTML sanitizes and validates the deck, persists it, applies access controls and CSP, and returns a viewer URL — plus the visual-QA expectation and the required disclosure when rendering tools are missing.

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

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

The opening sentence is well front-loaded, but the middle is a long, comma-chained run-on about rendering, re-rendering, and print-size inspection that could be tightened. Much of it earns its place as procedural guidance, but the density costs 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 five parameters, nested sharing/styleRef objects, no output schema, and no enum hints, the description covers the return value (viewer URL), the sanitization/access-control behavior, and the recipe dependency. It leaves sharing-mode differences and the styleRef read-permission requirement to the schema rather than restating them.

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 html, title, sharing, styleRef, and presentation. The description adds only marginal semantics (html must follow the recipe; recipeId selection guidance for the preceding get_recipe call) and does not explain the sharing modes or style provenance beyond 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?

States a concrete verb and resource ('Create slides ... as a first-class HTML presentation') and enumerates the artifact genres it targets, so the agent knows this is a deck-publishing tool. It does not, however, distinguish itself from the sibling publish_html/publish_page tools, which is the main differentiation gap.

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 explicit workflow prerequisites: call get_recipe first, with a conditional recipeId choice ('pm-decision-deck' for a PM seeking a product decision, otherwise 'presentation-deck'). It also states the visual-QA obligation and the fallback disclosure when rendering is unavailable. It stops short of naming when to prefer a sibling like publish_html instead.

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 real context beyond the annotations: it saves the previewed draft verbatim, produces an owner-private reusable template, and explicitly does not publish a page or change default styles. Idempotency is restated (already in annotations), but the non-publishing and no-default-change guarantees are genuinely new and important for a mutation tool.

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

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

Three short sentences, front-loaded with the approval precondition and the scoping constraint, then idempotency, then the non-publishing guarantee. No filler or restated 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 a single-parameter mutation with no output schema, the description covers precondition, idempotency, and side-effect boundaries (no publish, no style change). What is missing is error/response behavior, but annotations and the minimal schema carry most of the remaining burden.

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 one parameter and 0% schema description coverage, the description compensates by explaining that draftId refers to the exact preview draft and that retrying the same draftId is idempotent. The UUID format itself is only in the schema, but the semantic meaning of the id is well covered.

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 (save a template) and scopes it precisely to 'the exact preview draft', which cleanly separates it from sibling tools like preview_template, publish_page, and update_page. An agent can identify the operation 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?

Gives a clear precondition — only after the owner explicitly approves that draft — which is exactly what an agent needs before invoking a save-from-preview mutation. It does not name an alternative sibling or state an explicit when-not case, 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 idempotentHint and destructiveHint, so the bar is lower. The description adds the precise condition for safe retries ('retries are safe only when draftId, expectedRevision, and clientRequestId are identical'), which is valuable beyond annotations. It does not describe the destructive side effect in detail, but that is partially covered by destructiveHint.

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

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

The description is two sentences with zero fluff. The purpose is front-loaded, and the retry condition adds high-value information 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 tool with no output schema, the description covers the essential operational aspects: what it does, key parameter semantics, and idempotency conditions. It does not mention explicit side effects beyond the destructive hint, but given the simple activation action and annotation coverage, it is sufficiently complete for an agent to invoke 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 0%, so the description must compensate. It explains the role of expectedRevision ('current') and clientRequestId ('stable') and implies draftId is the identifier, providing semantics that the bare schema lacks. It does not fully define each parameter but gives enough operational 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 ('Activate') and a precise resource ('the exact private draft the owner reviewed'), making it clear this tool activates a specific draft style. It implicitly distinguishes from siblings like get_artifact_style (read) and preview_artifact_style (preview) by focusing on activation after review.

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

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

The description provides usage context ('after review') and operational guidance ('Use the current expectedRevision and a stable clientRequestId'), but does not explicitly compare to alternatives or state when not to use this tool. The distinction from publish or preview tools is implied but not stated.

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

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

Annotations already convey destructiveHint=true and readOnlyHint=false, and the description does not contradict them. It adds useful context by requiring an expectedRevision from get_page_sharing, hinting at optimistic concurrency, and by noting that restricted methods are OR alternatives. It does not describe side effects of overwriting existing sharing or behavior on stale revisions, but the annotations cover the core 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?

The description is only three sentences with no filler, and each sentence contributes information about access modes, restricted methods, or the revision prerequisite. It is compact and front-loads the main choices, though its brevity contributes to missing parameter detail.

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

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

For a mutation tool with a complex three-variant policy and no output schema, this description omits important invocation details like how to identify the page, expiration behavior, and exact restricted-method semantics. The schema and annotations fill some gaps, but the description alone is not complete enough for reliable use.

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

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

With 0% schema description coverage, the description must compensate, but it only lightly covers policy modes and the revision source. It does not explain pageId, expiresAt, or the detailed restricted method options such as password, recipients, and emailDomain. The phrase 'restricted methods are OR alternatives' adds some meaning but is too vague to carry the schema's full semantics.

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 the core action via 'Choose owner-only, public, or restricted access,' clearly mapping to the private, public, and restricted policy modes in the schema. The tool name and title reinforce that this sets page sharing, so an agent can identify the purpose. It does not explicitly differentiate itself from sibling tools like get_page_sharing, but the mutation intent is clear.

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

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

The description provides one concrete prerequisite: use the revision returned by get_page_sharing, implying the correct call sequence. It does not explicitly say when to prefer this tool over siblings or when not to use it, leaving usage context mostly 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 indicate mutation, idempotency, and destructiveness. The description adds valuable behavioral context by specifying that the page is not deleted and the shareable URL stays stable. This goes beyond what the raw annotations alone communicate and helps set accurate expectations.

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

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

The description is a single, front-loaded sentence with no filler. Every phrase carries meaning: the action, the resource, and two important non-effects. It is an efficiently structured description.

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 mutation tool, the description covers the core operation, what is preserved, and what does not change. Annotations supply idempotency and destructive-safety context, and no output schema is needed for a mutation like this. Nothing essential is missing.

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

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

The schema has one required parameter, pageId, but description coverage is 0% and the description does not explicitly explain it. However, the name 'pageId' plus the description's reference to 'a page' makes the parameter's meaning reasonably inferable. The description adds little beyond the schema, but the semantic gap is small.

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 ('take offline'), a resource ('a page'), and scopes the operation by what it does not do ('without deleting it or changing its shareable URL'). This clearly distinguishes it from sibling tools like delete_page and update_page. An agent can tell exactly what this tool accomplishes.

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 phrase 'without deleting it' implicitly signals when to choose unpublish_page over delete_page, and 'without changing its shareable URL' distinguishes it from update_page. It provides a clear usage context, though it does not explicitly name alternatives or say 'use this instead of X when...'.

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=true, idempotent=false, and openWorld=true, so the description's job is added context. It delivers that: optimistic concurrency via expectedVersion, conflict recovery behavior, an untrusted-source warning, and the non-obvious side effect that omitting styleRef clears recorded style attribution rather than CSS. It stops short of stating the concrete blast radius of the replace (e.g. what happens to existing page content/versions).

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 core action and URL guarantee, then workflow and caveats in tight imperative clauses. Slightly dense and mildly repetitive ('review' appears twice), but nearly every sentence carries an actionable instruction.

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 six-parameter destructive mutation with no output schema, the description covers the important operational edges: concurrency control, conflict handling, approval gating, and the styleRef side effect. It is only incomplete on the remaining input semantics (html/title/generationId) and what a successful replacement returns or invalidates.

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 17%, so the description must carry more weight. It usefully explains where expectedVersion comes from (get_page) and the omission semantics of styleRef, but html, title, pageId, and generationId get no treatment at all, leaving roughly half the parameters semantically thin.

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 with scope: 'Replace a page with new static HTML while preserving its shareable URL.' The replace-semantics-and-URL-preservation detail cleanly separates it from publish_page, unpublish_page, and set_artifact_style without opening their schemas.

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

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

Gives explicit routing: use get_page's includeHtmlSource for presentations, the authoring file otherwise, and 'expectedVersion from get_page'. It also names the failure path ('On conflict, reread and review') and the review/approval precondition, leaving nothing to inference.

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