Bisque Presentations

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

Beyond the annotations, the description adds valuable behavioral context: slides without the required narration markup 'publish SILENT,' and creation is asynchronous, requiring polling until ready. It does not elaborate on the destructiveHint=true annotation, but it does not contradict it, and the added silent-failure warning is genuinely useful.

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 sentences with no filler: it states the core action, the critical prerequisite, and the follow-up step. Every sentence earns its place, and the most important warning 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 13-parameter complexity and availability of an output schema, the description covers the essential workflow: prerequisites, the silent-failure risk, and polling. It does not mention sibling-tool selection or destructive implications, but the core invocation context is sufficiently complete.

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

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

Schema description coverage is 77%, so most parameters are already documented. The description adds meaning around the main input by tying the html-presentation/v1 document to the narration markup requirement, but it does not otherwise explain parameters beyond the schema. This is adequate but not exceptional.

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.' This clearly identifies what the tool does. However, it does not explicitly distinguish itself from the sibling publish_narrated_presentation, so an agent may have to infer the relationship between creating and publishing.

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 usage guidance: call get_presentation_spec before authoring, follow it exactly, and poll get_presentation_status after creation. This is clear operational context. It does not, however, explain when to choose this tool over publish_narrated_presentation or other siblings, so exclusion guidance is missing.

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 valuable scope constraints: it only covers 'own published briefings' and notes that personal email providers are filtered from domains. These details are not in the annotations and give the agent insight into what data to expect and the tool's boundary conditions. No contradiction with annotations.

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

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

Two sentences with zero filler. The first sentence front-loads the purpose and the full list of analytics fields. The second sentence clarifies the scope (own published briefings). Every word earns its place, and the structure is logical: purpose → 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?

Given the tool's simplicity (one parameter), existing output schema, and annotations covering safety, the description is comprehensive. It lists the analytics fields, notes the publisher ownership scope, and mentions filtering of personal providers. It does not explicitly address error handling or non-published presentations, but those are secondary given the schema and annotations. Slight room to mention what happens if the presentation doesn't exist or isn't published, but overall it's complete enough for an agent to call correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the presentationId parameter. The description refers to 'one of your presentations' which maps to presentationId but does not elaborate on the ID's format, provenance (e.g., from list_presentations), or validation. It gives minimal semantic context beyond the schema's type and length constraints. A stronger hint about how to obtain a valid presentationId would raise this 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 states a specific verb ('Watch'/'read') and resource ('analytics for one of your presentations'), enumerating concrete metrics (views, likes, completion rate, per-slide retention, traffic sources, viewer counts, domains) and the scope ('its own published briefings'). This clearly distinguishes it from siblings like get_presentation_status or get_presentation_context, which serve 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?

The description implies when to use this tool: when an agent needs performance metrics for its own published presentations. It explicitly mentions the scope ('own published briefings') and lists the data types, which indirectly differentiates it from alternatives like get_presentation_status (status) or list_presentations (listing). However, it does not explicitly name sibling tools or provide 'when not to use' guidance, so it stops short of 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?

Annotations already declare readOnly, idempotent, non-destructive; the description reinforces this with 'for reading' and adds concrete behavioral context: it loads metadata, timestamped narration transcript, and the context.md file, and it supports both URL or handle+slug targeting. No contradiction with annotations, and no hidden mutating side effects are implied.

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, each with a distinct job: enumerate what is loaded, explain how to target it, and state the supported use cases with the slide-citation convention. There is no filler or repetition of schema/annotation data.

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, three-optional-parameter tool, the description covers identification, payload contents, ownership scope, and downstream usage/citation behavior. With an output schema and safety annotations present, no essential caller-facing information is missing.

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

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

The main description adds the target-selection semantics that the schema leaves implicit: either the full watch URL or the handle+slug pair, with an example URL format. It also states the presentation need not be owned, which clarifies authorization scope. Slug still lacks its own schema description, but the OR-combination guidance compensates for the 67% schema coverage.

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 identifies the action ('Load... for reading') and resource (shared Bisque presentation), and enumerates the distinctive payload: metadata, per-slide transcript with timestamps, and the author's context.md. It does not explicitly name sibling tools, so the differentiation from get_presentation_spec/analytics/status relies on the reader inferring that 'context/reading' is not those read-only views.

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 concrete usage context: use this when the task is to read, summarize, cite, or answer questions from a presentation, and it clarifies that the target need not be owned by the user. It does not explicitly state when not to use it or name alternative tools for metrics/spec/status.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds the important behavioral context of ordering: this must be called before create_presentation, and skipping it leads to missing audio in published documents. This is useful beyond what annotations provide and does not contradict them.

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 accomplish everything: the first states the resource and its scope, the second gives the critical usage directive and consequence. There is no repetition of annotation data or filler, and the key workflow warning is front-loaded into the second sentence with clear emphasis.

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 parameterless, read-only fetch with an output schema available, the description is complete. It tells the agent what will be retrieved, when to call the tool, and why it matters. The missing-audio consequence communicates operational importance without requiring the description to duplicate output-schema details.

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 parameter semantics are essentially non-applicable; the schema carries no burden. The description instead clarifies what the fetched contract contains, which is appropriate for a no-argument tool. The baseline for zero parameters is 4, and nothing here lowers 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 uses the specific verb 'Fetch' and names the exact resource, the 'html-presentation/v1 authoring contract'. It then enumerates the contract's contents—document structure, the dual landscape/vertical layout rule, and narration markup—making the tool's purpose unmistakable and distinct from siblings like get_presentation_analytics or get_presentation_status.

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

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

The description gives an explicit workflow directive: 'Call this BEFORE authoring for create_presentation', reinforced with a concrete consequence for skipping it ('documents written without it publish with missing audio'). It does not explicitly discuss when not to use the tool or compare it to alternatives, but the timing and purpose are clearly stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral detail beyond the scope of what is fetched; it doesn't mention polling, error behavior, or URL availability timing. No 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?

One short sentence with no redundant words; the key action and target are front-loaded.

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

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

For a simple read-only, idempotent getter with one self-explanatory parameter, an output schema, and safety annotations, the description conveys the necessary purpose. The presence of an output schema means return-value detail is not the description's job.

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 has 0% description coverage, so the description must compensate, but it merely restates 'for a presentationId' without adding format, source, or lifecycle context. The parameter name is self-explanatory, but the description adds essentially nothing beyond the schema property.

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 ('Fetch') and resource ('build state and result URL') scoped to a presentationId, and its focus on build status clearly separates it from siblings like get_presentation_spec, get_presentation_context, and 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?

The description implies the tool is for checking a presentation's build status and result URL, which gives clear context. However it does not explicitly say when to choose this over siblings, nor list alternatives or exclusions.

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, and non-destructive behavior. The description adds useful authentication scope but does not disclose pagination, default visibility behavior, or any rate-limit considerations.

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 redundant content. The title and description align with zero 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 simple, read-only list operation with an output schema and safety annotations, the description covers the essential scope. It lacks minor context like pagination or filtering defaults, but nothing 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 0%, and the description does not compensate by explaining limit or visibility. Although the parameter names and enum are self-explanatory, the description adds no meaning beyond the raw 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 (List) and resource (presentations), and scopes it to the authenticated user. This clearly separates it from the get_presentation_* siblings, which target a single presentation, and from create/publish.

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 makes clear that this is for enumerating the user's presentations, which implies the main use case. However, it does not explicitly state when to prefer it over get_presentation_* or when not 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 already mark this as destructive, so the description need not restate that. It adds useful behavior not visible in annotations: the two-step upload flow (PUT MP3s/assets then POST completeUrl), server-side cue recomputation, and re-publish carry-forward/reuse semantics with staleSlides. It is slightly less explicit about destructive overwrite effects, but the annotation covers that baseline.

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 dense but well organized, front-loading the core behavior, then the upload workflow, then the RE-PUBLISHING section. A few clauses (e.g., 'free, unlimited, and works on macOS, Linux and Windows') are contextual rather than invocation-critical, but the structure keeps the important guidance easy to parse.

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 13 parameters, an output schema, and rich annotations, the description covers what an agent needs: the full call/response workflow, re-publish behavior, stale-slide remediation, and the alternative tool. Nothing critical for correct invocation appears to be 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?

With 85% schema coverage, the schema carries most parameter detail; the description adds high-level meaning by explaining how the audio array and returned URLs fit into the publish workflow and by clarifying re-publish audio optionality. It does not fully compensate for the undocumented voiceStability field, but that gap is minor given the schema richness.

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

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

The description names a specific verb and resource ('Publish an html-presentation/v1 document using audio YOU synthesized locally') and immediately distinguishes it from the sibling that server-narrates. It leaves no ambiguity about what this tool is for.

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 explicit selection criteria: use this for locally synthesized narration, and 'Use create_presentation instead to have the server narrate.' It also states exactly when re-publishing can omit audio, covering a major conditional use case.

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 reveals non-obvious behavior beyond the annotations: the avatar is fetched from a URL, center-cropped, and resized; an empty description clears the channel and reverts to auto-naming with newest presentations. This adds significant value beyond the idempotentHint annotation and 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 dense but economical, using three sentences to cover scope, each field's semantics, and the optional/default behavior. Every sentence contributes new information, and the core 'update one of your channels' framing 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?

With only three optional parameters, no enums, an output schema present, and annotations covering idempotency and safety, the description supplies everything an agent needs to call the tool correctly. It explains defaults, field combinations, clear behavior, and image processing without requiring the agent to infer anything.

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 schema already documents all three parameters, the description enriches each one: it explains what the description line appears in, what empty means behaviorally, and how the avatar image is processed. This goes well beyond the parameter descriptions and disambiguates edge cases like clearing the description.

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 'Update one of your channels,' naming a specific verb and resource, and immediately scopes it to owned channels. It distinguishes the operation from presentation-focused siblings by talking exclusively about channel metadata. No ambiguity remains about what the tool is for.

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 practical context: pass either or both fields, and omit handle to target the default channel. There are no alternative channel-update tools among the siblings, so a when-not-to-use note is unnecessary. The guidance is useful but stops short of explicitly contrasting with alternative operations.

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