Bisque Presentations

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

The description adds substantial behavior beyond the annotations: it waits for the page to be ready and returns its URL, it is private by default, pages are persistent and versioned, and pages with capabilities state.read/state.write interact with JSON documents via window.bisque.state. None of this contradicts the annotations, and the write nature is appropriately conveyed by 'Publish'.

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 compact paragraph with no filler. Core publish semantics come first, followed by privacy, the special state/capabilities case, and finally the sibling alternative. Every sentence earns its place and the most important decision cue 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 tool with 10 parameters, nested objects, and an output schema, the description covers the essential decision points: what to pass, what happens at call time, privacy defaults, interactive-state behavior, and which sibling to choose instead. Since an output schema exists, not detailing the return shape is acceptable; the description even names the returned URL.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description adds meaning beyond the schema by telling the agent to 'Pass the whole document as content', explaining the practical purpose of capabilities, and illuminating audience/share_with privacy semantics. It does not cover every parameter, but it doesn't need to given the exhaustive schema.

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

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

The description opens with a specific verb and resource: 'Publish an HTML page or a Markdown document as a Bisque Artifact', and then characterizes the artifact as persistent, versioned, and stable-URL. It explicitly distinguishes itself from create_presentation and references update_artifact, so an agent can tell this tool apart from its siblings without opening 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?

It states when to use the tool for publishing HTML/Markdown documents and gives a clear exclusion: 'For a narrated presentation use create_presentation instead.' It also sketches when state capabilities and state.rules are needed for interactive pages, and how privacy behaves unless audience or share_with is passed.

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, which simply mark the operation as non-read-only and non-idempotent, the description adds meaningful behavioral detail: the comment is made 'as the agent', an unanchored thread becomes a general page comment, and the thread is immediately active. It also documents mention syntax, improving transparency about how the tool behaves.

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 concise sentences each convey distinct useful information: the core action, the anchor behavior, and the thread lifecycle plus mention syntax. Nothing is redundant or padded.

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 nested anchor parameters and an output schema, the description is notably complete: it explains the main behavioral variants and the required body format. It could have explicitly listed which sibling tools handle replying or resolving, but those are already evident from the sibling names and the description's lifecycle note.

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 covers all parameters at 100%, providing a strong baseline. The description adds value by clarifying that omitting the anchor produces a general page comment and by giving explicit mention format instructions for the body parameter. This goes beyond the schema text without needing to repeat nested anchor details.

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 begins with a specific verb and resource: 'Leave a new comment thread on one of your Artifacts.' It also differentiates from siblings by emphasizing this is a new thread and by describing behaviors such as being 'activated from the start' and being reply/resolvable later.

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

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

The description clearly indicates the general use case and key decision points, such as whether an anchor is provided, and notes that the thread can later be replied to or resolved. However, it does not explicitly name sibling tools like reply_to_artifact_thread or resolve_artifact_thread as the alternatives for those later actions, so the guidance stops short of fully explicit 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=false and destructiveHint=true, so the safety profile is known. The description adds genuinely useful behavior beyond that: narration runs in the background and tracks itself, the silent-publish failure mode when the spec is ignored, and the expected response timing ('reply to the user as soon as this returns'). No contradiction with annotations. Slightly more could be said about the idempotency nuance hinted at by presentationId, but the disclosure is strong.

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: purpose in the first, the critical precondition in the second, async behavior and response guidance in the third. Dense but well-ordered and front-loaded. Loses a point only because the packed second/third sentences could be marginally clearer with line breaks.

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 15-parameter tool with a rich schema and an output schema present, the description addresses the real confusion points: the spec prerequisite, the status-polling temptation (get_presentation_status sibling), and the silent-publish failure mode. It doesn't enumerate return fields, but the output schema covers that, so nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description references the input document format (html-presentation/v1) and implies the spec precondition, but doesn't add parameter-level meaning beyond what the schema already documents in detail. This is acceptable given the schema carries the heavy lifting.

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 — 'Generate a narrated presentation from an html-presentation/v1 document' — with the input format named explicitly. It distinguishes from siblings like publish_narrated_presentation (publishing vs creating) and get_presentation_status (checking vs creating), so an agent can pick it without opening 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?

Provides explicit sequencing: 'BEFORE authoring, call get_presentation_spec and follow it exactly' — a hard precondition with a concrete failure consequence ('publish SILENT'). It also names the alternative it should NOT call ('do not call get_presentation_status unless the user asks whether it is done'), giving both when-to and when-not-to 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?

Beyond the annotations (destructiveHint, idempotentHint), the description adds valuable behavioral context: the URL stops working for everyone, and the agent must confirm with the user before invoking. This significantly clarifies the impact and safety 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?

Two concise sentences front-load the action and consequence, followed by the critical user-confirmation requirement. Every word earns its place with no unnecessary filler.

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

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

For a single-parameter destructive tool with a robust schema and annotations, the description covers ownership, global impact, and confirmation. The presence of an output schema means return-value details are unnecessary here.

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 artifact_id parameter is already well documented in the schema. The tool description does not add parameter-specific details, but none are needed given the complete 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 the exact action ('Delete an Artifact'), the resource type, and adds the ownership constraint ('you own'), which distinguishes it from sharing, updating, or listing artifacts. It is clear and specific.

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

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

The description gives clear context for when to call it: only for an artifact the user owns, and only after user confirmation. It does not explicitly name alternatives or exclusions, but the destructive nature makes the intended use 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, idempotentHint, and destructiveHint, so the safety profile is covered by structured data. The description adds useful behavioral context about the returned Version viewer state and the published_version_id null condition during publication preparation, which annotations do not convey.

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 states the core action first, then lists returned fields and a key nuanced edge case. Every clause earns its place with no filler or redundancy.

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

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

This is a simple single-parameter read operation with complete schema documentation, rich annotations, and an output schema. The description covers the tool's purpose, primary return fields, and an important publication-state nuance, leaving no critical gap for an agent to call it correctly.

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

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

Schema description coverage is 100% and artifact_id is already well-documented with a pattern and example. The description does not add additional parameter-level meaning beyond restating that it reads one Artifact, so it meets the baseline but does not exceed 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 opens with the specific verb 'Read' and the singular resource 'one Artifact', making the tool's scope immediately clear. It also enumerates the returned fields (title, access, published_version_id, URL), which distinguishes it from sibling tools like list_artifacts and get_artifact_thread.

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

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

'Read one Artifact' provides clear context that this is the single-item read tool, contrasting with list_artifacts for multiple items. It does not explicitly name the alternative or state when not to use it, so it stops short of a 5.

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

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

Annotations already establish this as read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that: it returns every message in oldest-first order and explains the mention syntax format present in message bodies.

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 short sentences with no filler. The first sentence establishes the core behavior and ordering, and the second provides essential content-format context, so 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?

For a simple read-only tool with two fully documented parameters, rich annotations, and an output schema, the description is complete. It covers what the tool returns, the ordering, and the special mention syntax the agent may need to interpret the 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 input schema already fully documents both parameters with descriptions and patterns, so the 100% schema coverage supports the baseline score. The description adds context about mention formatting but does not add new parameter-level meaning beyond the schema.

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

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

The description uses a specific verb ('Read'), identifies the exact resource ('one comment thread on an Artifact'), and specifies scope ('one thread'). It is clearly distinguishable from sibling tools like list_artifact_threads, create_artifact_thread, and reply_to_artifact_thread.

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

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

The description clearly conveys this tool is for reading a single full thread, which implies the appropriate use case versus listing or modifying threads. However, it does not explicitly name alternatives or state when not to use the tool.

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

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

Annotations already flag read-only, idempotent, non-destructive behavior, so the description doesn't need to restate those. It adds behavioral context beyond annotations by listing the metric categories, noting that personal email providers are filtered in the organization domains metric, and restricting scope to the agent's own published briefings.

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

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

Two sentences with no filler; the first sentence front-loads the resource and a comprehensive metric list, while the second clarifies ownership scope. Every phrase contributes either purpose or behavioral context.

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, read-only tool with an output schema present, the description is complete: it specifies what the operation does, what data is returned, and what scope it applies to. There is no additional information an agent needs to decide whether to call it or to know what to expect.

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 single parameter presentationId is fully documented in the schema (100% coverage), including the expected value and what it refers to. The description doesn't add syntax or constraints beyond that, so a 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 uses a specific verb, 'watch' (i.e., read/retrieve), paired with the resource 'analytics for one of your presentations,' and enumerates the exact metrics provided. This clearly distinguishes it from sibling tools like get_presentation_status or get_presentation_spec, which address different aspects of a 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 phrase 'for one of your presentations' and 'how its own published briefings performed' make the target scenario explicit: an agent that needs performance analytics for a presentation it published. It doesn't name alternative tools or explicitly exclude them, but it gives enough context to infer when this tool applies.

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 meaningful context beyond annotations: it works on any shared presentation ('does not have to be yours') and lists the return payload (metadata, transcript, context.md), which is valuable operational 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, each earning its place: the first defines what is loaded, the second explains targeting, and the third gives usage and citation guidance. No filler or redundancy; the most important information 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?

An output schema exists, so return values are covered elsewhere. The description supplies the necessary behavioral context (any shared presentation, the citation convention) and covers both targeting methods, making it complete for an agent to call the tool correctly.

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

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

Schema coverage is 100% with all three parameters described. The description restates the url-or-handle+slug alternative, but this is already documented in the url parameter description ('Provide this OR handle + slug'), so the description adds no new semantics 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 (Load) and resource (shared Bisque presentation) and enumerates exactly what is loaded: metadata, per-slide transcript with timestamps, and context.md. It also clarifies the tool is for reading any shared presentation, distinguishing it from siblings like get_presentation_spec by focusing on the full reading context.

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

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

Provides explicit usage direction ('Use this to read, summarize, cite, or answer questions about a presentation') and a concrete citation convention ('cite slides as [slide N]'). It does not name alternative tools to exclude, but the context for when to use it is clear and 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful context about the system-level consequence (missing audio) beyond what annotations provide, though it doesn't mention any tool-specific behaviors like rate limits or authentication.

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, followed by a critical usage instruction. Every word earns its place; no redundancy or filler.

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

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

The description covers the functional scope (what the spec contains), the workflow context (before create_presentation), and the risk of omission. An output schema exists, so return-value details are not required in the description. The description is complete for an agent to correctly invoke this 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?

The tool has zero parameters, so the schema is trivially complete (100% coverage). Baseline for 0-param tools is 4, and there is no parameter information to add; the description appropriately doesn't invent any.

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 ('Fetch') and resource ('the html-presentation/v1 authoring contract'), and enumerates its contents (document structure, layout rule, narration markup). This clearly distinguishes it from sibling tools like get_presentation_analytics or create_presentation, which have different 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?

Explicitly states when to use it: 'Call this BEFORE authoring for create_presentation', and provides a concrete consequence of not doing so ('documents written without it publish with missing audio'). This leaves no ambiguity about the workflow position.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's 'fetch' behavior is consistent and sufficient on the safety front. The description adds a little context by specifying what is fetched (build state, result URL), but it does not disclose any additional behavior such as polling implications or possible states.

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

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

The description is a single sentence that front-loads the action and the key outputs. Every word contributes: verb, resource, and parameter scope.

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

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

For a one-parameter, read-only status tool backed by a full output schema and strong annotations, this is essentially complete. It could add a sentence about expected use after create/publish, but such context lives partly in the parameter description and is not essential for correct invocation.

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

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

The input schema has 100% description coverage and the only parameter is well documented as the presentationId returned by create_presentation or publish_narrated_presentation. The tool description merely repeats the parameter name without adding extra format, lifecycle, or constraint details, so it stays at 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?

The description uses a specific verb ('fetch') and names a concrete resource aspect ('build state and result URL') scoped by presentationId, so an agent knows what the tool returns. It does not explicitly call out sibling tools, but the focus on build state/result URL is enough to distinguish it from analytics, context, and spec 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?

No explicit guidance is given about when to use this tool instead of get_presentation_analytics, get_presentation_context, get_presentation_spec, or list_presentations. The intended use is only implied by the tool name and the short description.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, non-destructive), so the description adds useful behavioral context: default scope, newest-first ordering, and the fields returned in each item. This goes beyond the structured data and gives the agent a concrete expectation of the result.

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

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

The description is a single dense sentence that front-loads the action and resource, then efficiently covers scope, ordering, and output shape. Every clause contributes, with 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?

For a read-only list tool with no required parameters, strong annotations, full schema parameter descriptions, and an output schema, the description is complete enough for an agent to select and invoke the tool correctly. The minor absence of explicit sibling routing does not create a correctness 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 100%, so the schema already documents all four parameters. The description still adds value by explaining scope semantics ('owned' means you own, 'shared' means shared with you, 'all' means both) and reinforcing the default. This is more than the bare enum values provide.

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

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

The description clearly states the action ('List'), the resource ('Artifacts'), and the scope options (owned/shared/all). It distinguishes itself from sibling tools like get_artifact, create_artifact, and list_artifact_threads by naming the exact resource and operation.

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

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

The description gives clear context for when to use the tool: listing artifacts by ownership scope, with the default spelled out and what 'shared' and 'all' mean. It does not explicitly name alternatives like get_artifact for single-item lookups, but the purpose is clear and no misleading guidance is present.

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, and non-destructive behavior, so the description is free to add value elsewhere. It discloses result ordering, the meaning of activated_only, and the fields each thread carries (anchor, version, preview, agent_activated) — useful behavior beyond 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?

Three sentences with no filler: the main action and ordering come first, the key filter guidance follows, and the payload summary closes. 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?

With a full schema, rich annotations, an output schema, and this description covering ordering, filtering semantics, and response contents, an agent has everything needed to select and invoke the tool correctly. Pagination and defaults are already covered by 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that activated_only threads are the actionable ones ('which are the ones you may reply to and resolve'), and it contextualizes the output fields relevant to choosing parameters.

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

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

The description opens with a specific verb and resource: 'List the comment threads people left on one of your Artifacts.' It also adds ordering ('newest activity first') and the activated_only filter, making it clearly distinct from the singular get_artifact_thread and the mutation siblings like reply_to_artifact_thread.

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

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

The description gives concrete guidance on when to use the activated_only filter, noting those are 'the ones you may reply to and resolve.' It implies the list-first workflow before reply/resolve, though it does not explicitly name sibling alternatives or exclusion conditions.

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 this as a safe, read-only, idempotent, closed-world read, so the safety profile is covered. The description usefully adds behavior those annotations cannot express: newest-first ordering, a per-call cap, and the exact continuation/termination rule for pagination.

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, and front-loaded with the resource and ordering before the pagination mechanics. Every sentence carries distinct information an 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?

For a read-only paginated list with an output schema, the description supplies everything the agent needs: scope, ordering, page size behavior, and the full continuation rule. Return value shape is correctly left to 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 coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by tying `limit` and `cursor` together into a loop and stating the termination condition when `nextCursor` is null, which the per-parameter schema text does not spell out.

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), resource (the authenticated user's presentations), and ordering (newest first), which is enough to separate it from siblings like list_artifacts and list_artifact_threads without opening any schema. The scope is explicit rather than tautological.

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 clearly describes the calling context for pagination: call again with `cursor` set to `nextCursor`, and repeat until `nextCursor` is null. It does not, however, say when to prefer this over sibling list tools or note any preconditions, so it stops short of full when/when-not guidance.

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

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

Annotations already mark destructiveHint=true, and the description adds substantial behavior beyond that: deprecation, the multi-step PUT/POST upload flow, rejection of a first publish with no audio, and response fields such as `reused`, `synthesized`, and `staleSlides`. 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?

The description is long but dense and front-loaded: deprecation and the replacement call appear first, followed by the upload workflow and re-publishing semantics. Every sentence earns its place for this complex tool, though the deprecation notice is restated from the title.

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

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

For a 14-parameter tool with an output schema and rich annotations, the description provides all decision-level context: deprecation, alternative tool, upload mechanics, carry-forward rules, and response reporting. An agent has enough to decide whether to call it and how to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds extra meaning beyond the schema by explaining that `audio` entries map from bisque-voice stdout, that omission carries forward prior audio, and that changing `speechSpeed` invalidates carry-forward. This is helpful context without merely restating 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: publishing an html-presentation/v1 document with locally synthesized audio. It also clearly distinguishes itself from create_presentation by declaring itself deprecated and naming the replacement call with an `audio` array.

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 call create_presentation with an `audio` array instead, and explains why it is preferable. It also covers when re-publishing can omit audio, when stale slides need re-synthesis, and when to use create_presentation for server-side narration.

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 discloses useful behavioral details beyond the annotations: the reply is posted as the agent, the thread must have agent_activated true, and the reply is publicly attributed as 'Agent · via <your name>'. These add context that readOnlyHint=false and destructiveHint=false do not convey. No contradiction with annotations exists.

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

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

The description is three short sentences, each carrying distinct information: the core action, the activation condition, and the visible attribution. It is front-loaded with the main purpose and contains no filler or redundant 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 three simple parameters, an output schema, and annotations, the description covers the essential preconditions and behavioral context needed for correct invocation. The only mild gap is the lack of explicit mention of alternative tools, but the activation rule sufficiently bounds usage.

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 67%, with thread_id and artifact_id already explained in the schema. The description does not add parameter-level meaning, but the body parameter is self-explanatory as the reply text and the schema constrains it to 1-4000 characters. This is adequate but not enhanced.

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 begins with a specific verb and resource: 'Post a reply in a comment thread as the agent.' It clearly identifies the action, the target object (comment thread), and the actor (the agent). This differentiates it from siblings like create_artifact_thread and resolve_artifact_thread, which are about creating or resolving threads instead of replying.

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

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

The description gives explicit when-to-use conditions: 'Allowed only on activated threads (agent_activated true)' and defines activation via two concrete cases. It does not explicitly name alternative tools, but it provides a clear exclusion boundary that prevents misuse on inactive 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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds useful behavior beyond these: the operation is performed 'as the agent,' only allowed on activated threads, and belongs to a reply-first workflow. This is meaningful context without contradicting the annotations.

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

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

Three dense sentences: the action, the prerequisite, and the recommended workflow sequence. Every sentence earns its place, and the core purpose 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?

Given the simple boolean toggle, the existing output schema, and annotations covering idempotence and destructiveness, the description supplies the remaining context: activation requirement, agent identity, and ordering relative to replies and republishing. 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?

Schema description coverage is 67%, with thread_id and artifact_id already documented. The description explicitly explains the otherwise-undocumented 'resolved' boolean parameter as true for resolving and false for reopening, compensating for the schema 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: 'Mark a comment thread resolved (resolved: true) or reopen it (resolved: false)' on an Artifact comment thread. It also notes 'as the agent,' which clarifies the acting identity and distinguishes this from thread creation, reply, and retrieval siblings.

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

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

The description gives concrete when-to-use guidance: resolve only after addressing the comment, usually after republishing the Artifact, and reply first so the person can see the change. It also states the activation prerequisite. It does not explicitly name alternatives or why they should be ignored, so it stops short of a 5.

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

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

The description explicitly says 'Going public deletes every comment thread' and that the change is refused unless delete_threads is true, which is a destructive side effect. The annotations declare destructiveHint=false, directly contradicting the description. This is an annotation contradiction.

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

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

Three dense sentences, no filler. Purpose is front-loaded, the replacement semantics and destructive caveat follow, and the return value is stated. 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 key operational details: ownership, audience selection, share_with replacement, the public/threads safety rule, and the returned URL. It is nearly complete, but the contradiction between the description and the destructiveHint annotation leaves the tool definition slightly unreliable overall.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds important semantics beyond the schema: share_with replaces the previous list and can be omitted to keep it, and delete_threads is required for a public change when threads exist. It also notes the returned URL.

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

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

The description opens with a specific action and resource: 'Set who can open an Artifact you own.' This clearly identifies the tool's access-control role and distinguishes it from create/update/delete artifact siblings.

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

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

It gives clear context for when to call the tool (changing who can open an artifact you own) and explains audience/share_with/delete_threads semantics. It does not explicitly name alternatives or state when not to use it, so it misses the top score.

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 valuable behavior beyond annotations: the whole document is replaced, not diffed; earlier Versions remain in history; the call waits for the new Version to be live; and capabilities/state rules are inherited unless explicitly overridden. This gives an agent a strong model of the tool's 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?

The description is compact, front-loaded with the core verb and resource, and every sentence adds useful information. It efficiently covers update scope, versioning behavior, field combinations, waiting semantics, and inheritance without repetition or filler.

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

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

Given the tool's complexity, the description is complete enough for an agent to call it correctly. The output schema exists, so return values need not be described; the description covers permissions, version behavior, parameter combinations, and inheritance rules, which are the main contextual 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 coverage is high (86%), so the schema already documents most parameters. The description adds meaning by explaining that content replaces the whole document, that title/description/icon are independent changes, and that capabilities/state are inherited unless passed. These semantics go beyond the schema's individual field descriptions.

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

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

The description uses a specific verb ('Change') and identifies a clear resource ('an Artifact you own or edit'). It also clarifies that passing content publishes a new Version at the same URL, distinguishing this update operation from creation or deletion.

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

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

The description states the precondition 'you own or edit' and explains when to pass content versus title/description/icon. It does not explicitly name alternative tools, but the versioning language and 'same URL' make the intended use case 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?

The description discloses important behavior beyond the annotations: an empty description clears the channel description and restores a fallback naming behavior, and the avatar is fetched, center-cropped square, and resized. It also clarifies the default-handle behavior. None of this contradicts the annotations, and the added context materially helps an agent predict 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?

The description is compact and front-loaded: the core action appears first, followed by specific parameter behaviors and default handling. Every sentence contributes useful information, and there is no filler or repetition of schema details beyond what adds operational meaning.

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 three optional parameters and no required fields, the description covers the important scenarios: what each parameter does, how to clear the description, how avatar processing works, and what happens when handle is omitted. Since an output schema exists, explaining return values is unnecessary. 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?

Even though the input schema documents all parameters, the description adds meaning beyond it: it explains what a stranger sees in search results or link unfurls, that an empty description clears it, that the avatar image is center-cropped and resized, and that parameters can be passed either or both. The 'omit handle for default channel' note is also valuable.

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

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

The description opens with a specific verb and resource, 'Update one of your channels,' and then clearly enumerates exactly what can be updated: the description and the avatar. It is immediately distinguishable from the presentation-focused sibling tools and leaves no ambiguity about its scope.

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 practical usage guidance: you can pass either or both of description and image URL, and omitting handle falls back to your default channel. It does not name an alternative because no sibling tool performs channel updates, but the guidance clearly covers the main decision points for calling it.

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