SlideForge

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

Annotations already establish a read-only, idempotent, non-destructive profile, lowering the burden. The description adds useful behavioral texture: ranked search, variant one-liners, example payloads, non-sendable choosers, and the fact that theme results are furniture layouts meant to be rendered via create_slide. No contradiction with the annotations.

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

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

The description is long but dense and front-loaded with the core browsing behavior, then organizes the many modes with delimiters and arrow syntax. The 'Free.' fragment is slightly ambiguous and the code-path section is packed, but every element mostly 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 complex browse tool with no output schema, the description is remarkably complete: it enumerates every major entry path, describes the shape of results for each mode, warns about the non-sendable contract case, and connects theme results to create_slide. An agent has enough to invoke the right mode and interpret what comes back.

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 ist 73%, so description must contribute for family, variant, and prior_id. It does partly: it explains family selects a form, variant/prior_id yield example payloads, and type=schema combinations produce chooser/contract outputs. However, family/variant/prior_id are still only implicitly defined, and some param combinations are left for the agent to infer.

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 ('Browse the PowerPoint slide catalog') and sets it apart from sibling creation/management tools. The description immediately signals this is the discovery/exploration entry point, and the mode list clarifies what 'browse' means in practice.

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 mode-by-mode usage guidance ('No args -> ...', 'family=<form> -> ...', 'q=<text> -> ...') and calls out when a result is not a sendable contract. It also names the relevant sibling (create_slide) for rendering returned theme layouts, so the agent knows the boundary between exploration and execution.

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?

The description discloses blocking/autofix behavior, cost thresholds ($0 invalid, $0.05 code, +$0.05 image), dry-run and polling behavior, and conditionality such as 'renders + bills only if faithful'. It goes well beyond the sparse annotations and matches them (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?

The text is heavily front-loaded with a dense first paragraph, and the menu/escape-mode sections are clearly organized. It is long by necessity given 37 forms, but a few interstitial notes (e.g., 'the generated,always-current JSON Schema') add verbiage without much semantic weight, so it is not maximally 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?

For a 42-parameter tool with no output schema, it covers the essential invocation workflow: forms, data shapes, per-form catalog lookup, modes, error recovery, costs, and image handling. Any return-value details are already captured by the detail/verify parameter descriptions in the schema, so nothing critical is missing.

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

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

The description supplies the entire form menu semantics that the schema's form parameter only points to, plus the blocks-vs-data split and the meaning of mode=code/status. With 93% schema coverage the baseline is 3, but this adds genuinely necessary routing semantics well 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 first sentence states the exact operation: 'Create one PowerPoint slide (.pptx, native, editable) from a structured intent in ONE call', with explicit form/brief paths and modes. 'One ... slide' and 'inspect' via mode=status distinguish it from sibling tools like create_deck and plan_slide without ambiguity.

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 explicit routing rules: choose a form or pass a brief, consult browse_catalog for new forms and exact data shapes, use mode=code when the menu cannot express the request, and use mode=status to poll. It does not explicitly contrast sibling tools such as create_deck or plan_slide, so it misses the full cross-tool when-to-use comparison.

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

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

Annotations only mark destructiveHint=true, so the description carries the transparency burden and handles it well. It discloses irreversibility of delete_job and delete_asset, Stripe checkout/wallet credit behavior, webhook push semantics, short-TTL download URLs, feedback resolution status, shared logo assets not being deleted, and deck child-slide rollup behavior. This is substantial behavioral context beyond the annotations.

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

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

The description has no fluff and is front-loaded with the tool's purpose. However, it is a long run-on paragraph of semicolon-separated action summaries, and the final delete_asset sentence is detached awkwardly. A bulleted structure would be easier for an agent to scan without losing density.

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 18 actions, 17 parameters, no output schema, and sparse annotations, the description is quite complete. It names key output differences, safety caveats, and action-specific conditions. It does not fully detail every action response shape, but combined with the rich input schema, an agent has enough to invoke the correct action.

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 adds meaningful action-level semantics not fully present in the schema, such as job detail differences for slide vs deck jobs, download_url's purpose, status meaning, and delete_asset's ownership constraint. That raises it to 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 clearly identifies the resource scope: 'SlideForge account for PowerPoint generation: balance, billing, job history, feedback, data controls.' It enumerates the actions, which distinguishes it from the sibling creation/catalog tools. It loses a point because it is a broad polymorphic tool rather than a single-verb action, so the purpose is clear but not maximally crisp.

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 triggers for several actions: use topup 'when a render is refused for balance', download_url 'when a result carries no inline URL', webhooks 'instead of polling to terminal', and feedback_list to check whether an earlier report was already resolved. It does not give an overall when-to-prefer-this-tool statement, but the account-management scope is distinct from siblings.

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?

Annotations are uninformative (all false), so the description carries the full burden and delivers richly: per-purpose pricing ($0.05, $0.02/slide, $0.10), 'render NATIVELY on the template (masters/layouts/chrome)', the drop-zone behavior where 'bytes never pass through the agent', and the recreate fallback ('annotate/preserve fallback, refusals free'). This goes far beyond what the schema or annotations 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?

Front-loaded intro sentence, one bullet per purpose, and a single closing paragraph for size and byte-handling notes; every sentence carries distinct information. The minor typos in the recreate bullet ('annotate/preserve fallback, refusals free') are the only blemish on an otherwise tight structure.

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, 8-enum-value tool with no output schema and no informative annotations, the description covers outputs (IDs), costs, constraints, and special behaviors (native template rendering, chained pdf→translate, drop-zone security). The only omission, the 'brand' enum synonym, is already handled in the schema, so nothing an agent needs 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% and the schema already explains purpose-conditioned parameters (target_language for translate, model overriding quality). The description adds what the schema lacks: max sizes (logo 5MB, image 10MB), costs per purpose, and the omit-data drop-zone behavior. Strong supplement, though the schema still carries substantial per-parameter semantics.

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 — 'Upload assets for PowerPoint (.pptx) generation' — and then enumerates each purpose with its returned ID and cost (logo→logo_id, theme→theme_id, translate→deck job_id). The detailed purpose list makes the tool's boundary unambiguous against siblings like create_deck, translate_deck, and browse_catalog.

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 purpose bullets function as a routing table — 'Use `image` to just place a picture' explicitly steers away from recreate, and the '>3MB' note gives a concrete condition for omitting `data`. However, it never names the translate_deck sibling or states when to prefer upload_asset(translate) over it, leaving one ambiguous branch.

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