Bisque Presentations

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

Beyond the annotations, the description discloses meaningful behavior: the artifact is persistent and versioned, the call blocks until the page is ready and returns the URL, and visibility is private unless audience or share_with is provided. It also mentions the update capability and the stable URL. This adds real value beyond the structured 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?

Four sentences, each earning its place: purpose, content requirement and behavior, privacy default, and sibling routing. The key facts are front-loaded and there is no redundant 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 rich input schema, annotations, and output schema, the description covers all essential agent-facing concerns: what it creates, how to pass content, the blocking behavior, the return value, the default privacy, and how to select an alternative. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful semantic reinforcement: 'Pass the whole document as content' clarifies the content parameter, and 'private to you unless you pass audience or share_with' clarifies the access-control behavior. This goes slightly beyond the schema 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 opens with a specific verb and resource: publishing an HTML page or Markdown document as a persistent, versioned Bisque Artifact at a stable URL. It distinguishes the tool from create_presentation and update_artifact, making its purpose unmistakable.

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

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

The description gives clear context: publish a document, pass full content, wait for readiness, private by default unless audience/share_with is passed. It explicitly names create_presentation for narrated presentations and mentions update_artifact for later updates, though it does not enumerate when-not-to-use cases for every sibling.

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?

The description adds meaningful behavioral context beyond the annotations: narration runs in the background, the inline player tracks it independently, and polling get_presentation_status is unnecessary unless the user asks. It also warns that slides without the required narration markup publish silently, which is critical behavioral information. These details are not present in the annotations.

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

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

The description is tightly written in four sentences, with the most important workflow directive front-loaded. Every sentence provides actionable information and there is 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?

Given the 13-parameter schema, output schema, and annotations, the description covers the essential operational context: prerequisite spec call, background narration behavior, return values, and the polling caveat. Nothing critical an agent needs to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description additionally explains the consequence of not following the spec in the indexHtml parameter (silent publishing), adding value beyond the raw schema. It does not cover every parameter, but it does not need to given the schema's completeness.

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 generates a narrated presentation from an html-presentation/v1 document, which is a specific verb and resource. It also names the return values (presentationId and watch URL). However, it does not explicitly distinguish itself from the sibling publish_narrated_presentation, so it falls just short of full differentiation.

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 workflow guidance: call get_presentation_spec before authoring, follow its narration markup exactly, and do not call get_presentation_status unless the user asks about completion. It does not, however, state when to choose this tool over publish_narrated_presentation or mention alternatives explicitly, so it is not a full 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?

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 declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the auth scoping that only the user's presentations are returned, which is useful. It does not mention pagination or ordering, but with annotations covering safety, a score of 3 is appropriate.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes meaning: the verb, the resource, and the 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?

This is a simple list operation with two optional parameters already fully described in the schema, and an output schema is present. Annotations cover safety, and the description states the scope. Nothing essential is missing for an agent to call it correctly.

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

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

The input schema provides complete descriptions for both parameters (100% coverage), so the description does not need to repeat them. It adds no additional meaning beyond what the schema already offers, warranting the baseline score.

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

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

The description uses a specific verb ('List'), a clear resource ('presentations'), and a scope ('authenticated user's'). This clearly distinguishes the tool from sibling get/create/update/publish operations, which target individual presentations or other actions.

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 a clear context: retrieving the authenticated user's presentations. It does not explicitly name alternatives or exclusions, but the list operation is obviously distinct from the sibling tools, so an agent can infer when to use it.

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

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

Annotations only mark the tool as destructive and not read-only; the description adds real behavioral context: the server assembles presentation.json, returns per-MP3 upload URLs, requires subsequent PUT/POST calls, and reports reused/synthesized/staleSlides. It stops short of explicitly describing overwrite or deletion semantics, but the destructiveHint annotation already signals that side-effect 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 information-dense but well structured: it front-loads the core action, uses a clear RE-PUBLISHING break for the complex re-publish behavior, and ends with sibling routing. Every sentence contributes either selection criteria, protocol steps, or edge-case handling.

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 13-parameter publish tool with a rich schema and an output schema, the description supplies the missing procedural glue: what to send, what to expect back, what to do next, when audio is optional, and the first-publish rejection edge case. An agent has enough context to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters thoroughly. The description adds high-level workflow context around audio reuse and stale slides, but it does not need to restate individual parameter meanings. The baseline 3 applies because the schema carries the parameter documentation burden.

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: 'Publish an html-presentation/v1 document using audio YOU synthesized locally.' It also distinguishes itself from the sibling by ending with 'Use create_presentation instead to have the server narrate,' so an agent can clearly tell when this tool is the right choice.

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

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

It explicitly defines the condition for using this tool (locally synthesized narration) and names the alternative (create_presentation for server narration). It also explains when re-publishing can omit audio entirely, giving clear situational guidance beyond the schema.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral nuance beyond those flags: content replaces the whole document (not a diff), earlier Versions remain in history (explaining why destructiveHint=false), and with content the call blocks until the new Version is live. This materially helps an agent understand side effects and response timing.

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 sentences, all earning their place: scope and permission first, then content behavior, then metadata fields, then combination/before-return behavior. 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?

The definition is complete for a mutation tool of this complexity. It covers who can use it, what each field does conceptually, the versioning model, non-destructive history, and synchronous behavior. An output schema exists, so omitting explicit return-value details is 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 80%, so most parameters are already documented. The description still adds meaningful semantics for the content parameter ('the whole document, not a diff') and clarifies that parameters can be used in any combination in a single call. It does not repeat the per-parameter schema details, which is appropriate.

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

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

States a specific verb ('Change') and resource ('an Artifact you own or edit'), then enumerates exactly what can be changed (content, title, description, icon) and the key behavioral consequence (publishes a new Version at the same URL). This clearly distinguishes update_artifact from create_artifact, delete_artifact, and get_artifact.

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

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

Gives clear context: use it to modify an existing artifact you own or edit, with a choice of content-based version publishing vs metadata field changes. It also notes that any combination can be sent in one call. It stops short of explicitly saying 'use create_artifact instead if the artifact does not exist yet', but the ownership/edit prerequisite makes the intended usage 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?

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.