SlideForge

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

Annotations already declare read-only, idempotent, and non-destructive, so the bar is lower. The description adds valuable context: it's free, progressive, and the type=schema+family response is explicitly 'not a sendable contract'. It also discloses that theme layouts must be rendered via create_slide. This goes beyond the annotation basics without contradicting 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?

The description is dense but every sentence/semicolon-separated clause carries meaning. It is front-loaded with the core purpose ('Browse progressively') and then enumerates modes. It's longer than typical descriptions, but the tool has 11 parameters and multiple distinct modes, so the length is justified. A bulleted structure would improve scannability, but there is no fluff.

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

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

Given the tool's complexity, no output schema, and 11 parameters, the description covers almost all modes and integration notes (e.g., render via create_slide). It does not explicitly mention source/top/limit/offset pagination controls, but these are documented in the schema. The description sufficiently orients the agent for most discovery flows.

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 description richly explains parameters that the schema leaves unexplained (e.g., family, variant, prior_id) and clarifies the meaning of type values beyond the schema's enum. It maps q to ranked search, name to widget contracts, and theme_id to branded furniture layouts. Schema coverage is 73%, and the description compensates for the gap, especially for family/variant.

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 browses the PowerPoint slide catalog and explains a progressive discovery workflow. It enumerates distinct modes (form overview, family variants, search, schema contracts, widgets, helpers, themes) and distinguishes it from creation/management siblings by focusing on discovery rather than mutation.

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 explicit context for when to use each mode (e.g., no args for overview, family= for variants, q= for search, type=schema for contracts, type=themes for branded layouts). It also points to create_slide as the rendering path for themes. It does not explicitly say 'use this instead of X', but the sibling tools are clearly different in purpose.

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?

With no annotation hints, the description carries the full transparency burden and delivers extensively. It discloses parallel rendering and merging, billing concepts ($0 blocks, free modes), retry behavior with can_autofix patches, and polling mechanics (deck_id == job_id). It also flags ignored parameters like force_render and allow_partial, and explains dry_run's all-or-nothing validation.

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 longer than average, but it packs substantial necessary information for a 17-param, multi-mode tool. The content is organized into logical segments: core purpose, blocking/retry, alternate modes, and polling. While dense and not perfectly structured, every sentence earns its place and there is no redundant re-listing of schema content.

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 is remarkably complete for a tool with no output schema and 17 parameters. It covers return values (pptx_url, repair_actions, dry_run manifest), job polling, billing, mode-specific behavior, and inheritance rules. It even explains how to handle blocked retries and points to browse_catalog for schema exploration, giving an agent everything needed to invoke the tool correctly in varied scenarios.

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

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

Schema coverage is high (88%), so the baseline is 3, but the description adds extra context beyond the schema. It explains that slides are create_slide intents with the same data shapes, that deck-level settings are inherited unless slide-level overrides exist, and that dry_run should be placed at deck level rather than on individual slides. These clarifications help avoid misuse despite the schema's own 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 'Create a complete PowerPoint presentation (.pptx): a whole multi-slide deck, native and editable, in one call,' which clearly states the core function with a specific verb and resource. It distinguishes create_deck from its sibling create_slide by emphasizing the multi-slide, whole-deck scope, and further clarifies alternate modes (assemble, fork) that repurpose the tool.

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 explicitly says slides are a list of create_slide intents and points to create_slide for the form, establishing expected usage. It gives clear when-to-use guidance for mode=assemble and mode=fork, and advises returning to browse_catalog for schema discovery when blocked. This provides both alternatives and exclusions (e.g., theme_id does NOT re-theme assembled decks).

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 are all false, but the description goes beyond them by disclosing billing behavior ('$0.05', 'renders + bills only if faithful; else $0 invalid report'), blocking with can_autofix patches, and the binding rule that unused fields are ignored-with-warning. It also explains dry_run costs and no-PPTX behavior. 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 a multi-paragraph wall topped by a 40-line form menu that largely duplicates what browse_catalog provides. It repeats the blocks format that's already in the schema, and the opening includes a block/autofix note before the form menu, burying the routing guidance. While detailed, it is far from concise.

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 has 42 parameters and no output schema, the description covers the essential operational context: form selection, data shapes, modes (safe/brief/code/status), blocked-render recovery, image handling, and cost/fidelity expectations. It directs to browse_catalog for exact schemas and examples, so an agent can operate correctly without external docs.

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 93%, so baseline is 3. The description adds a cross-cutting rule: 'Fields tagged (per-form) bind only where the form has that slot — ignored-with-warning elsewhere' and clarifies blocks vs data shapes, which enriches parameter understanding. However, much of the param detail repeats schema descriptions, so it doesn't exceed a 4.

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 'Create one PowerPoint slide (.pptx, native, editable) from a structured intent in ONE call', which clearly states the verb, resource, and scope. It distinguishes from siblings by emphasizing single-slide creation and routing through forms, and refers to browse_catalog only as a reference, not as the primary action.

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 provides explicit when-to-use and alternatives: 'mode=code ... use for forms the menu cannot express: calendars, custom diagrams' and 'New form: browse_catalog(type=schema) first.' It also explains the brief-routing fallback and how to handle blocked renders via can_autofix. This gives clear usage guidance and 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 indicate destructive potential (destructiveHint=true). The description adds crucial specifics: delete_job and delete_asset are 'irreversible', webhook registrations are push endpoints, and download_url mints 'short-TTL single-use' links. It also notes feedback requires asking the user. 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 a single dense paragraph but front-loaded with purpose. Every action has a terse parenthetical explanation. It could be better structured with bullets or separation of destructive actions, but it remains reasonably concise given the breadth of operations.

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 17 parameters and 16 actions, the description covers all actions and hints at output details for some (status returns balance+plan, job includes quality_warnings). The schema covers parameter specifics. No output schema exists, so description partially compensates by mentioning return fields. Missing error/edge-case context, but acceptable for the complexity.

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 baseline is 3. The description adds high-level action context (e.g., 'slide jobs include quality_warnings[]') but does not systematically explain each parameter beyond the schema. It neither compensates nor repeats; it offers marginal extra semantic value.

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 scope: 'SlideForge account for PowerPoint generation: balance, billing, job history, feedback, data controls.' It enumerates specific actions (status, usage, jobs, etc.) and distinguishes itself from sibling tools focused on content creation (create_deck, create_slide). The verb+resource structure is specific and 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 contextual guidance for several actions: webhooks are recommended 'so you don't poll async jobs to terminal', download_url should be used 'when a result carries no inline URL', and topup is implied for balance issues. It does not explicitly state when to avoid this tool in favor of siblings, but the account-management scope is self-evident.

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

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

Annotations already indicate readOnly/idempotent, and the description adds significant behavioral context: route.confidence is a calibrated probability, retrieval scores are raw classifier values, and escalate ensures plan/create agreement. This goes far beyond the annotation hints.

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-structured: it front-loads the purpose, then explains response fields and the relationship to create_slide. No wasted sentences, though the level of detail is high.

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

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

No output schema exists, but the description thoroughly documents the response format (route, input, next_action, confidence, scores, source) and the escalate behavior. It also connects to the larger workflow, making the tool's usage complete despite the missing 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 covers escalate and variant_policy but omits descriptions for brief and top. The description partially compensates by calling the brief 'short' and implying it is a slide brief, but it never explains what 'top' controls (likely number of candidates). At 50% coverage, the gap is not fully bridged.

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

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

The description states a specific action: 'Plan a PowerPoint slide before rendering' and details the output (ranked candidates, route/input/next_action). It distinguishes itself from the sibling create_slide by explicitly instructing to call create_slide afterwards.

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 provides clear when-to-use guidance ('before rendering'), an explicit next step ('Then call create_slide'), and explains the free tier ('Free (one embedding)') and escalate behavior. This effectively tells the agent when to invoke plan_slide versus the alternative.

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 context beyond annotations: cost ('$0.02/slide'), language scope ('32 languages (Latin, Cyrillic, Greek scripts)'), and formatting preservation. The annotations are all false, so this extra context is valuable for the agent.

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 concise sentences, front-loaded with the core purpose, followed by cost, language support, and input sources. Every sentence contributes unique information with no 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 10-parameter tool with no output schema, the description covers the essential invocation context: purpose, cost, supported languages, and source alternatives. It doesn't describe return values, but the rich schema descriptions and cost details make it reasonably 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 100%, so the baseline is 3. The description's mention of source options mirrors schema descriptions rather than adding new semantic meaning; it doesn't elaborate on parameters like concise_mode or include_notes beyond what's already 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?

The description clearly states the action ('Translate a PowerPoint (.pptx) deck') and a key differentiator ('preserving all formatting'). This distinguishes it from siblings like create_deck and create_slide, which focus on creation rather than translation.

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 explicit input options ('Provide job_id (from a previous create_slide/create_deck), pptx_url, or pptx_base64') and references prior tools, implying a workflow. It doesn't explicitly state when not to use, but no competing translation sibling exists.

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?

With annotations all false, the description fully carries behavioral disclosure. It reveals costs ($0.05, $0.02/slide, $0.10), file size limits (5MB for logo, 10MB for image), the drop-zone fallback for large files ('bytes never pass through the agent'), and the recreate fallback ('honest annotate/preserve fallback, refusals free'). These are beyond what the schema or annotations state.

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 front-loaded with a summary sentence, then uses a concise bulleted list for each purpose. Each bullet is information-dense but easily scannable, using bold labels and arrows for outputs. Despite covering seven purposes and multiple edge cases, it remains readable and every sentence contributes value.

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 10-parameter, 7-purpose tool with no output schema, the description covers all major behaviors, special cases, pricing, and parameter interactions. It also supplements the 100% schema coverage with critical operational details (drop-zone for large files, native rendering on templates, fallback behavior for recreate). An agent has enough information to select the correct purpose and invoke the 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?

Although schema coverage is 100%, the description adds high-level purpose-to-parameter mappings that the schema lacks. For example, it specifies that `prompt` is required for generate_image, `target_language` is required for translate, and `data` can be omitted for large pdfs. It also clarifies output IDs (logo_id, asset_id, theme_id, job_id) and acceptable file types (PNG/JPG/SVG) that are not 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?

The description opens with a clear statement: 'Upload assets for PowerPoint (.pptx) generation: company template, logo, image, or document — or AI-generate an image.' It then enumerates seven specific purposes, each with a distinct verb and expected output (e.g., 'logo → logo_id', 'theme → theme_id', 'recreate → editable PPTX slide'). This differentiates it convincingly from sibling tools like create_deck and translate_deck.

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 strong contextual guidance per purpose: translate requires `target_language`, pdf can chain to translation, and recreate explicitly says 'Use `image` to just place a picture' to avoid mis-selection. It also advises omitting `data` for files >3MB and for recreate on chat hosts. However, it does not explicitly compare to sibling tools (e.g., when to use translate_deck instead of the translate purpose), so no explicit exclusions are given.

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