Bisque Presentations

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false) it discloses the things an agent actually needs: the call blocks until the page is ready, it returns the URL, the default visibility is private to the caller, sandbox restrictions on external resources, and the run-time capability model. It also clarifies that scripts cannot fetch anywhere and libraries must be version-pinned, which prevents a whole class of failed publications.

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

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

Front-loads what the tool produces and the privacy default, then layers the interactive-page case and the alternative. Dense but every sentence carries information; some sentences are long and the state/capabilities discussion could be split for scannability, so not a 5.

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

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

For an 11-parameter, nested-schema, capability-bearing creation tool with an output schema, the description covers the decision-relevant surface: default visibility, blocking-then-URL semantics, content sandbox rules, the state/capabilities model, and the sibling alternative. Return values are documented by the output schema, so leaving them to it is appropriate.

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 carries the heavy lifting and a 3 is the baseline; the description earns an increment by explaining the intent behind capabilities and state.rules (a page that must remember a checklist/poll/sign-up) and by stating 'Pass the whole document as content'. That usage-level framing adds meaning the property descriptions alone don't convey, though the per-field detail remains in the schema.

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

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

Opens with a specific verb and resource ('Publish an HTML page or a Markdown document as a Bisque Artifact') and immediately defines the resulting object as a persistent, versioned page at a stable URL. It also names the sibling to use instead when the goal is a narrated deck (create_presentation), so an agent can discriminate it from neighbors without reading schemas.

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

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

Gives clear positive usage context (whole document as content, update later with update_artifact, declare capabilities only for interactive pages) and one explicit alternative ('For a narrated presentation use create_presentation instead'). It stops short of full when-not guidance — e.g., it never says when to use share_artifact or create_artifact_thread instead of folding sharing into this call — but the routing it does provide is concrete.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's job is to add blast-radius detail — and it does: the URL stops working for everyone, and the caller must own the artifact. It stops short of stating whether deletion is reversible or permanent, which would be the final piece for a destructive tool.

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

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

Three short sentences, front-loaded with the action and scope, then the impact, then the safety instruction. No wasted text.

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

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

Output schema and annotations cover return shape and safety profile, and the description adds ownership and cross-user impact. The only meaningful gap is whether deletion is permanent or undoable, which matters for a destructive operation.

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

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

Schema coverage is 100% and the artifact_id description already explains the art_ prefix and where the id appears in URLs. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ("Delete an Artifact") and scopes it to artifacts the caller owns, which cleanly separates it from siblings like get_artifact, update_artifact, and share_artifact. An agent can identify the operation without opening the schema.

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

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

Implies the precondition of ownership and adds an explicit procedural rule ("Confirm with the user before calling this"), which is real usage guidance. It does not contrast against alternatives such as update_artifact for non-destructive changes, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is covered elsewhere. The description adds real behavioral context beyond that: published_version_id is null while a publication is still being prepared, and content is only present for markdown documents. That prevents wrong assumptions about nulls and missing fields.

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

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

Two tight sentences, front-loaded with the verb and resource, followed by the returned fields and the id hint. No filler and nothing out of order.

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

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

With an output schema present and a single required parameter, the description covers what an agent needs to call it correctly, plus the markdown-only caveat. It adds a bit of return-value detail that the output schema already handles, which is harmless but redundant.

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

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

Schema coverage is 100% and the artifact_id parameter is thoroughly documented there, including the art_ prefix and pattern. The description's 'Pass the art_… id from the end of the link' largely restates the schema's own wording, so it adds little beyond the baseline.

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

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

States a specific verb and resource ('Read one Artifact') and enumerates exactly what comes back (title, access, published_version_id, URL, markdown content). That is clearly distinguishable from list_artifacts and get_artifact_thread, which the description implicitly excludes by scoping to a single 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?

The clause 'so a linked document is read in one call' implies the intended scenario (following an art_… link) and motivates using this instead of a multi-call read. But no sibling tool is named as the alternative, and there is no explicit 'when not to use' guidance, so usage is only implied.

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

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

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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that the response includes a result URL, but says nothing about terminal vs in-progress states, polling cadence, or failure behavior for an async build.

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

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

A single front-loaded sentence with no filler; the resource and the returned fields come first.

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

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

An output schema exists, so return values need no explanation, and the one parameter is fully documented. The only gap is guidance on polling/when to call it, which is minor for this simple status reader.

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

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

Schema description coverage is 100%, and the parameter description even names the producing tools, so the description's mention of 'a presentationId' adds nothing new. Baseline 3 is correct when the schema does the work.

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?

Names a specific verb ('Fetch') and a specific resource ('build state and result URL') scoped to a presentationId. It distinguishes itself well enough from generic readers, but does not explicitly contrast with close siblings like get_presentation_spec or get_presentation_analytics.

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

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

Usage is only implied: 'build state' suggests polling after an async creation, and the schema note referencing create_presentation / publish_narrated_presentation reinforces that, but the description never states when to call it or that polling is the intended pattern.

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, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds valuable behavioral context beyond these: it specifies the ordering (newest first) and the fields included in each item (id, title, who can open it, URL). No contradictions with annotations. It doesn't discuss pagination details, but the cursor parameter covers that.

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

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

The description is two sentences long, front-loaded with the primary purpose and scope options. The second sentence adds concrete detail about the returned items without fluff. Every word earns its place, making it concise and well-structured.

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

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

Given the presence of an output schema (not shown but referenced), full parameter documentation in the schema, and annotations covering safety and idempotency, the description is complete for an agent to call the tool correctly. It covers the scope behavior, ordering, and item fields, leaving nothing essential missing. Pagination is handled by the cursor parameter, which the schema documents.

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 with descriptions. The description does not add new meaning beyond what the schema provides; it reiterates the scope options and mentions the order, but these are also in the schema. Per the rubric, with high schema coverage, the baseline is 3, and the description doesn't exceed that.

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's action (list) and resource (Artifacts), and differentiates itself from sibling listing tools by specifying the scope options (owned, shared, all) and the default. It also mentions the order (newest first) and what each item contains, making its purpose unambiguous.

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

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

The description provides clear context on when to use the tool: to list artifacts by ownership scope. It doesn't explicitly state when not to use it or point to alternatives, but the scope options and the existence of sibling tools like list_presentations and list_artifact_threads imply differentiation. The description covers the primary usage scenario well.

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?

Beyond the annotations, it discloses the side effect that going public deletes every comment thread, the guard behavior (request refused unless delete_threads is true), and the replacement semantics of the share list. It also notes the return value (the URL), which the annotations cannot convey. The thread deletion sits in mild tension with destructiveHint=false, but because the operation is refused by default rather than silently destructive, this reads as disclosed opt-in behavior rather than a 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?

Four sentences, each carrying distinct load: purpose, list-replacement rule, destructive-change guard, return value. The most consequential caveat (thread deletion) is placed before the trivial return-value note.

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

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

With an output schema present and full parameter documentation, the definition covers what an agent needs to call it safely, including the ownership precondition. The remaining gap is interaction between the listed flag and audience, and the ambiguity of supplying share_with alongside an explicit audience.

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, and the description genuinely adds semantics the schema does not: share_with is a complete replacement list and may be omitted to preserve the current one. It does not explain how listed interacts with audience, nor what happens if audience is passed with a share_with list, so it falls short of 5.

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

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

"Set who can open an Artifact you own" gives a concrete verb plus resource and implicitly scopes itself to sharing rather than general editing. It stops short of naming the boundary against update_artifact, which also mutates artifact metadata, so an agent must still infer which one owns permission changes.

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 the decision rule for audience, explains that share_with replaces rather than appends, and gives an explicit conditional for delete_threads (public change on a threaded artifact is refused unless true). What is missing is any comparison to a sibling tool for general artifact updates.

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

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

Goes well beyond the annotations by disclosing that content replaces the entire document rather than a diff, that earlier Versions persist in history, that the call blocks until the new Version is live, and that capabilities/state rules are inherited from the base Version unless overridden. These are exactly the mutation-side effects (what is destroyed, what is preserved, timing) that readOnlyHint=false and destructiveHint=false cannot 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?

Five short sentences, front-loaded with the ownership constraint and the content-vs-metadata split, then the inheritance caveat. No filler and nothing repeated from the schema verbatim.

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

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

With an output schema present the return values need no explanation, and the description covers the mutation semantics, blocking behavior, and inheritance defaults. It stops short of failure modes — permission denial, missing artifact, or what happens on concurrent content updates.

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 already 88%, so the baseline is 3, but the description adds real meaning: content is the whole document of the same type, and capabilities/state default to inheriting the base Version's rules when omitted. That defaulting behavior is not stated in the schema and is the most likely source of a wrong call.

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?

Opens with a specific verb+resource ('Change an Artifact') and immediately bounds scope with the ownership/editing precondition. It also clarifies that the tool serves both metadata edits and whole-document republication, which is what separates it from create_artifact and delete_artifact, though no sibling is named explicitly.

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?

'Change an Artifact you own or edit' establishes a clear precondition and 'Any combination in one call' explains that updates should be batched rather than split. It gives no explicit exclusions or pointers to alternatives like delete_artifact or create_artifact for the cases where this tool is the wrong choice.

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.