Dreambooth Studio

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

The annotations already declare readOnlyHint and idempotentHint, and the description reinforces this by saying it 'creates nothing' and 'is always safe to call.' It goes well beyond the annotations by explaining that 'running' means nothing exists yet, that frame and design outputs are only previews/drafts until saved or created, and that booth creation is the one case where something exists afterward.

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: purpose, calling convention, polling cadence, and per-status payload meanings each appear in a logical order. Every sentence earns its place because removing any section would lose operational details needed for correct use.

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 output schema exists and the annotations cover safety, the description still adds the missing operational picture: time estimates, polling intervals, what each done-state payload means, and the distinction between previews, drafts, and created resources. An agent can call this tool correctly end-to-end based on the description alone.

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 the schema already describes jobId, the description adds important operational meaning: the id must be kept for the conversation, works for 15 minutes even across re-authentication, and omitting it silently falls back to the most recent job. This is exactly the kind of parameter behavior an agent needs to invoke the tool correctly.

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 ('Report on background work') and explicitly names the five starting tools it complements. This clearly distinguishes check_generation from all sibling tools such as start_frame or save_frame.

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 calling rules: always pass the returned jobId, use the no-argument form only as a recovery fallback, and poll every 15 seconds while waiting. It also tells the agent to wait 10-15 seconds rather than polling tightly and explains what to do with the results, which is actionable guidance an agent can follow without guessing.

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 flag it as non-readonly, open-world, non-idempotent. The description goes well beyond that, enumerating the three possible statuses, explaining that a link is returned for awaiting_approval but not for use_client_sign_in, that accounts are created on first sign-in, and that repeated calls while pending are improper. This is rich behavioral context an agent could not infer from 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?

Front-loaded with the core action and then structured by status branch, which is the right shape. It is somewhat long and repeats the 'ask them to...' instruction pattern, but nearly every sentence carries an actionable distinction (link vs no link, don't recall while waiting).

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 OAuth-style connect flow with an output schema covering status, the description supplies everything an agent needs: trigger conditions, per-status handling, and the constraint against premature re-invocation. Return-value mechanics are 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?

The tool takes no parameters, so there is no parameter semantics to document; the description correctly avoids inventing any. Per the zero-parameter baseline this caps at 4 rather than 5, since there is no schema content for the description to enrich.

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 ('Connect this conversation to the person's Dreambooth Studio account') and the scope of the action. It is clearly distinguishable from siblings like connection_status or check_generation, which merely report state.

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 call: 'Call this when another tool reports that no account is connected, or when someone asks to connect or switch accounts.' It also gives a when-not-to-act rule ('do not call this tool again while waiting'), which is unusually strong 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 cover readOnly, idempotent, and non-destructive traits. The description adds genuinely new context beyond those: 'Cheap and read-only — it does not contact Dreambooth.' This discloses that no network call occurs, which is valuable and not derivable from the annotations alone.

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 tightly packed sentences, front-loaded with the core purpose, followed by usage guidance and behavioral disclosure. Every sentence earns its place with no filler or repetition 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?

Complete for a simple parameterless status check: the description covers purpose, when to call, and behavior (no external contact), while annotations carry the safety profile and the output schema presumably documents the return value. 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?

The tool has zero parameters, so there is nothing the description must explain; the 100% schema coverage and 0-param signature make parameter documentation a non-issue. The baseline for a parameterless tool 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?

The description states a clear purpose: report whether a Dreambooth account is connected to the current conversation and which one. It implicitly distinguishes itself from siblings — it concerns connection state, not projects, credits, revenue, or wallet data — and names its direct sibling (connect_account) for contrast.

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, actionable guidance: 'Call this if you are unsure whether to run connect_account first.' This names the relevant alternative and the condition that selects this tool. It lacks an explicit when-not-to-use clause, but for a cheap status check that is a minor gap.

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 sparse (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) and carry no contradiction — the description's mutation claim matches readOnlyHint=false, and idempotentHint=false matches 'creating twice makes two booths'. The description then goes far beyond annotations: it discloses the slow async nature (2-6 minutes, frames up to five minutes), that it reads draft state first, the early-stop failure mode when the slug is taken, that the booth is live/unlisted immediately, and the side effects of adding starter frames and the default filter. This is exemplary behavioral disclosure for a mutating, non-idempotent 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?

The description is long (13 sentences), but it is front-loaded with purpose and logically sequenced: purpose → precondition → process → parameter defaults → timing → return value → failure mode → idempotency caveat → edit/delete limitation. Every sentence carries unique information for a genuinely complex tool (7 params, async, stateful, non-idempotent). There is slight redundancy in enumerating the draft-carried fields and the drawn-frame steps, but for this complexity the density is justified. A 5 would require trimming; 4 is fair.

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 this complex — asynchronous, stateful, non-idempotent, with side effects and a failure path — the description is remarkably complete. It covers preconditions (draft seen and approved), the full process (read draft, check slug, draw frames, add starters/filter, create), timing (2-6 min), the return shape (job id; check_generation yields link, id, dashboard link), the slug-collision recovery path, and the absence of any edit/delete tool. The output schema exists and handles return details, so the description's inclusion of return context is bonus. The only omission, authentication requirements, is covered by sibling tools connect_account/connection_status and annotations. Nothing an agent needs to invoke this 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 coverage is 100% and each parameter (slug, title, draftId, frameIds, filterIds, captureMode, aiEffectTitle) already carries a solid schema description with patterns and 'leave unset' defaults, so the baseline is 3. The description adds genuine value beyond the schema by explaining the cross-tool relationship: 'Frames saved with save_frame and filters made with create_filter on this connection are carried automatically; ids can also be passed.' This clarifies that frameIds/filterIds are optional overrides on top of auto-carried state — context the schema alone cannot convey.

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 opening phrase 'Create the booth from a finished draft — the step that makes something real, live at its public link' states a specific verb (create), a precise resource (booth), and the defining precondition (finished draft, going live). This cleanly distinguishes it from siblings like update_booth_draft (draft editing), check_generation (progress reporting), and start_booth. An agent can tell them apart without opening any 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?

Explicitly states when to call it ('only after the operator has seen the draft via check_generation and agreed to create it'), which sibling to rely on afterward (check_generation reports progress and the public link), and what NOT to expect ('there is no tool that edits or deletes a booth — changes happen in the dashboard'). The non-idempotency warning ('Creating twice with different link names makes two booths') is critical routing guidance. Nothing is left to inference.

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 annotations already signal a non-read-only, non-idempotent operation, and the description adds concrete behavioral context: creating the same filter twice yields two filters, no existing filter is modified, and retries after uncertainty should be avoided. This adds real value beyond the annotations rather than 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?

Every sentence earns its place: purpose and translation duty, explicit trigger condition, edit/delete routing, and non-idempotency warning. It is compact enough to read quickly while conveying all operation-critical guidance.

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 create operation with nested parameters, an output schema, and annotations, the description covers the ambiguous natural-language-to-numbers mapping, the no-edit/delete limitation, and the duplicate risk. Nothing needed for correct invocation is missing; response shape is already supplied by 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% and each parameter has a description, so the baseline is high. The description still adds useful semantics by instructing the agent to translate look descriptions into adjustment numbers, to include only what the operator asked to change, and to treat omitted adjustments as neutral. That is valuable but not essential given the schema's already detailed parameter docs.

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: create a new photo filter on the operator's account from a natural-language description. It also distinguishes itself from siblings by explicitly stating there is no edit/delete tool, so an agent won't confuse this with duplicate_project or preview_filter.

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 an explicit trigger condition — 'Call this only when the operator asks for a filter to be CREATED' — plus an explicit exclusion: it does not change an existing filter and edit/delete requests should be sent to the dashboard. It also advises against retrying calls that may have gone through, which is directly actionable.

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 this is not read-only, not idempotent, and not destructive. The description adds meaningful behavior: the copy is named after the original, is not published at the original's public address, is safe to make, and can be renamed in the dashboard. No annotation contradiction.

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

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

The description is front-loaded with the core action, then efficiently covers when to use, prerequisites, side effects, and alternatives. Every sentence contributes useful guidance 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?

Given a single parameter, a high-coverage schema, and an output schema, the description is fully complete. It covers use cases, prerequisite steps, post-copy behavior, safety, renaming, and the relevant alternative 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?

Schema coverage is 100% and the single parameter is already documented as the id from list_projects, not a name or slug. The description reinforces this but adds no genuinely new semantic detail beyond what the schema provides.

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 ('Copy') and resource ('one of this operator's existing booths'), and clarifies it copies settings into a new booth. It also distinguishes itself from start_booth, 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?

Explicitly says when to use it ('when they want another booth like one they already run'), names the prerequisite list_projects call, and directs users to start_booth for building a NEW booth from a description. This is strong routing 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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable non-obvious context: reads-only with no generation/creation, a 7-day lifetime on the operator's account, and that the result includes the full draft state accumulated since check_generation.

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 core read behavior and key scoping detail are front-loaded, followed by concrete use cases and the lifetime constraint. Every sentence contributes actionable information.

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 tool with a full output schema and safety annotations, the description covers behavior, usage timing, data scope, and retention. Nothing essential is missing for an agent to select and invoke 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%, but the description adds meaning by specifying the draft is identified by draftId and that the value originates from check_generation or a previous tool result. This helps the agent source the parameter correctly beyond the schema's pattern and 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 identifies a specific verb ('Read') and resource ('booth draft by its draftId') and differentiates it from related tools by noting it returns the same summary as check_generation plus accumulated draft data. It is clearly distinguishable from create_booth and update_booth_draft.

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 scenarios: when the start_booth job is untracked, before create_booth, or to confirm update_booth_draft changes. It does not explicitly name tools to avoid, but the referenced workflow tools make the intended context clear.

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

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

The description adds a behavioral nuance by noting credits are separate from wallet money, which is beyond the read-only/idempotent annotations. It does not contradict the annotations, though it does not elaborate on side effects (which are unnecessary given 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 concise and well-structured, with a clear functional statement followed by usage guidance and a clarifying note, all in two sentences without redundancy.

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

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

It provides sufficient context for the agent to decide when to call the tool, including the distinction from wallet transactions. It does not mention error cases or output format, but that is not essential for selection given the output schema is noted as existing.

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 no parameters, so the description correctly remains silent on parameter details. There is nothing to add beyond the empty schema, and the coverage is effectively complete.

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 retrieves the operator's remaining AI credit balance and subscription plan, and explicitly distinguishes it from wallet money, making its purpose unambiguous even without seeing the output 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?

It provides explicit call scenarios: 'when they ask how many credits are left, whether they can still run AI effects, or what plan they are on,' which directly guides the agent on when to use this tool versus alternatives.

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 agent knows this is a safe, side-effect-free read. The description adds value by clarifying the return payload ('counts only, not the media itself') and the retention-window behavior. This goes beyond what annotations convey, giving the agent concrete expectations about the output shape and scope. 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 two sentences that immediately state the core purpose and then give a concrete usage trigger. It front-loads the most critical information (what it returns) and then explains when to use it. There is zero filler or redundant phrasing; every word 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 the annotations covering safety, the schema fully documenting parameters, and an output schema present (though not shown), the description covers everything an agent needs to call this tool correctly. It explains the return type (counts only), the scoping to booths, and the retention nuance. Nothing essential is missing for a read-only statistics 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 schema description coverage is 100%, with both projectId and includeExpired having clear descriptions. The tool description itself does not add any parameter-specific meaning beyond what the schema already provides; it only implies the general context of booths and retention. Since the schema fully documents the parameters, the description adds no extra semantic value, so the baseline of 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 opens with a precise statement of what the tool does: it reports how much media an operator's booths have produced, broken into total, still active, and expired past retention. This is a specific verb-resource pair that clearly distinguishes it from sibling tools like get_sessions or get_revenue_summary. The phrasing 'Returns counts only, not the media itself' further disambiguates the 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 explicitly says when to call it: 'Call this when the operator asks how many photos or videos a booth has taken, or whether media is being lost to retention.' This gives clear triggering conditions. It does not name alternative tools for contrast, but the guidance is specific enough that an agent can decide without confusion. A minor omission is not stating when NOT to use it, but the positive triggers are strong.

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 annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the description adds no conflicting side effects. It clarifies that the returned status is live, though it does not mention error or rate-limit behavior; given the annotations, this is sufficient.

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, front-loaded with the tool's purpose and output fields, followed by clear usage guidance and a prerequisite. There is no redundant or vague wording.

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 output schema exists and the description enumerates the output fields and use cases, the tool is fully specified for an agent to call correctly. It names the prerequisite tool and the distinguishing scenario, covering all necessary context.

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 has 100% coverage with a meaningful description for projectId, and the tool description reinforces that the id should come from list_projects first. This goes beyond the schema by providing the source of the parameter 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 'Get' a single booth's full detail, listing specific fields (name, public link, currency, screen size, live device status). It is distinct from siblings like list_projects and get_sessions, so an agent can easily select this tool for one specific booth.

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

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

It explicitly says to call this tool when the operator asks about one specific booth or whether a booth is working. It also instructs to get the project id from list_projects first, providing clear operational guidance and preventing misuse.

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 cover safety (readOnlyHint, idempotentHint, non-destructive), which is confirmed and not contradicted. The description adds genuinely useful behavioral context beyond the annotations: the fact that revenue includes cash and vouchers that bypass the wallet ledger, and that below-minimum-reporting threshold amounts are never recorded — disclosure that helps the agent interpret results correctly rather than trust a misleadingly low wallet figure.

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, front-loaded with the primary purpose. There is minor redundancy (the cash/voucher channel enumeration appears both at the start and in the wallet explanation), but each sentence earns its place — the wallet-routing note is critical disambiguation. A tighter single-sentence pass could trim a few words without harming clarity.

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 3-parameter, 0-required tool with a rich output schema and complete annotations, the description is complete: it covers purpose, all revenue channels, grouping dimensions, currency, the extra-print/AI-effect subcategory, and the wallet understatement edge case. The output schema handles return-value details, so nothing an agent needs to call it 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 coverage is 100%, so the description doesn't need to re-document parameters. It reinforces the groupBy semantics by referencing grouping ('grouped by month or day and by currency') and adds the 'omzet' term that expands the query vocabulary the agent can map to this tool. No contradictions, and it doesn't over-repeat what the schema already states.

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+resource ('Business revenue from this operator's photobooth sessions') and enumerates the exact scope: every payment channel, grouping by month/day and currency, with extra-print and AI-effect revenue reported separately. It clearly distinguishes itself from siblings like get_wallet_transactions by explicitly flagging the wallet-vs-revenue distinction.

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 when-to-use guidance ('Use this for any question about income, revenue or omzet') and an exclusion with rationale: it is the right tool when wallet earnings look too small because cash/voucher money never reaches the wallet ledger. This proactively prevents the most likely misrouting to get_wallet_transactions.

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 description does not need to repeat these. The description adds no extra behavioral context (e.g., auth, rate limits), but it does not contradict the annotations. Adequate given the existing 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 two sentences, front-loads the primary action, and avoids redundancy. It efficiently covers purpose, usage, and alternatives without unnecessary detail.

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 that an output schema exists (context signal), the description does not need to explain return values. It provides the purpose, when to use, and a clear alternative tool, which is sufficient context for an agent to decide when to invoke it.

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 each of the 7 parameters having its own description. The tool description reinforces the date-range, per-booth filtering, payment status, and payment channel parameters but adds no new information beyond what the schema already provides. 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 clearly states that the tool lists photo sessions with totals, and explicitly distinguishes it from get_revenue_summary by focusing on session counts rather than money totals. The verb 'List' and resource 'photo sessions' are 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?

It explicitly says when to call the tool ('when the operator asks how busy a booth has been, how many sessions ran in a period, or wants to inspect individual sessions') and when not to ('For money totals... use get_revenue_summary instead'). No ambiguity.

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 annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context about the data scope (excludes cash/voucher income, newest first) and the ordering, which goes beyond the annotations. It does not describe any side effects, but given the readOnly annotation, none are expected. The description is transparent about what data is included and what is not.

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. The first sentence defines the content and ordering of the ledger. The second sentence provides usage guidance and the distinction from get_revenue_summary. It is tight, focused, and every word contributes to clarifying the tool's purpose and appropriate use.

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 provides all necessary context for an agent to decide when to use this tool: it explains the data scope, the ordering, the intended use cases, and the crucial caveat about cash/voucher income. It also points to the correct sibling tool for income queries, ensuring the agent selects the right tool for the user's intent. No additional context is needed.

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 covers 100% of parameters (from, to, limit) with descriptions and types. The tool description does not add any additional semantic meaning beyond what the schema already provides. Since the schema is complete, the description does not need to elaborate, but it also doesn't enhance understanding of the parameters. This is a baseline score for when schema handles the 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?

The description clearly states what the tool does: it returns the operator's wallet ledger with gateway earnings, withdrawals, and refunds, ordered newest first. It also explicitly distinguishes it from get_revenue_summary by noting that wallet excludes cash and voucher income, and directs users to the sibling tool for income questions. This leaves no ambiguity about the tool's purpose.

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 states when to use the tool (for questions about the wallet, payouts, or withdrawals) and when not to (for income questions, since it understates revenue for cash operators). It even names the alternative tool (get_revenue_summary) to use instead. This gives clear, actionable 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the exact fields returned and explicitly stating what is NOT included (designs, layouts), which helps set expectations. 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?

Two sentences, no fluff. The first sentence front-loads the key purpose and fields, the second provides usage guidance and a negative. Every clause contributes necessary information, and the description is immediately scannable.

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 no parameters, an output schema exists to document return values, and annotations cover the read-only nature, the description provides all necessary context: what it returns, when to call it, and what it doesn't cover. An agent has everything needed to invoke it correctly without ambiguity.

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 and the schema is empty, so there is nothing to describe. The baseline for 0 params is 4, and the description appropriately adds no unnecessary parameter detail. It doesn't need to compensate for schema gaps because there are no 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 states a specific verb ('List'), a specific resource ('photobooth projects this operator owns'), and enumerates the returned fields (id, name, public link slug, active status, currency). It also differentiates from siblings by positioning itself as the first call needed to obtain project IDs for filtering other tools, which clearly separates it from get_project and other getters.

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 instructs 'Call this first whenever the operator names a booth' and explains why (you need the project id to filter any other tool by booth). It also states what it does not return ('Does not return booth designs or page layouts'), giving clear exclusion criteria. This is direct and actionable 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?

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful behavior beyond those signals: it uses either a sample photo or the operator's dashboard preview photo, runs the exact booth pipeline, returns an image URL, and reports certain adjustments as notPreviewed. It ends with 'Nothing is created by this tool,' reinforcing the read-only nature 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?

The description is four sentences, front-loads the core purpose, and every sentence carries useful information about behavior, usage, or limitations. It is slightly redundant with the annotations ('Free and read-only', 'Nothing is created'), but that redundancy is mild and reinforces the read-only contract rather than wasting space.

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 annotations cover safety/idempotence, the output schema covers return values, and the schema covers all parameter semantics, the description fills the remaining contextual gaps: when to use it, how to iterate with create_filter, and what to tell the operator about non-previewed adjustments. Nothing essential is missing for correct invocation.

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

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

The schema already provides excellent coverage of every adjustment parameter with descriptions and ranges, so the baseline is 3. The description adds extra value by naming which specific adjustments (shadows, highlights, whites, blacks, clarity, dehaze, vibrance, texture) cannot be previewed and will be listed as notPreviewed, which is parameter-level behavioral information not present 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 precise statement of what the tool does: 'Show what a filter would look like BEFORE creating it,' then explains the rendering pipeline and that it returns an image URL. It clearly distinguishes this from the sibling create_filter by emphasizing that nothing is created, so an agent can tell them apart immediately.

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 to call it 'whenever the operator is designing a filter,' gives an iterative workflow ('adjust the numbers from their reaction... preview again'), and tells the agent to switch to 'create_filter with the same adjustments only once they are happy.' It also warns about non-previewable adjustments, giving the agent concrete guidance on how to handle the output honestly.

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 flag destructive/non-idempotent/open-world; the description goes well beyond them by disclosing the redraw budget (5 redraws, 3 full generations), the exact cost of each 'what' and orientation combination, what cannot be edited directly, and that it returns a job id to be polled via check_generation. This is exactly the operational context an agent needs before consuming a scarce resource.

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?

Dense and front-loaded with the most important constraints, but it reads as one long paragraph mixing usage rules, budget accounting, and parameter semantics. All content earns its place; minor structural cost only.

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 destructive, budget-limited mutation tool with an output schema, the description covers prerequisites, mode semantics, budget accounting, and the required follow-up call. Nothing an agent needs to invoke it 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 coverage is 100%, but the description still adds real meaning: it explains enumeration members ('everything' rebuilds from a NEW full description), the interaction between 'welcome' and orientation (1 vs 2 redraws, omit to redraw both), and per-mode instruction intent and limits beyond what the schema states.

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

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

States a specific verb ('change a booth draft') plus the exact resource ('from start_booth', identified by check_generation's draftId), and clearly separates itself from siblings like update_booth_draft and refine_frame by describing a redraw-based mutation rather than a direct edit.

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 when/when-not guidance: 'Call only when the operator asks for a change — never iterate on your own,' and routes 'everything' to the case where the operator 'wants a different booth, not a tweak.' It also names check_generation as the required follow-up and pre-requisite source of draftId.

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 show readOnlyHint=false and destructiveHint=false, but the description adds crucial behavioral context: each call consumes part of the daily allowance, it returns immediately with a job id, and earlier thread versions remain available to save_frame, so reversibility is guaranteed. This goes well beyond the structured annotations.

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

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

Four sentences, each earning its place: examples of prompts, required threadId source, strict when-to-use rule with cost rationale, immediate-return behavior, and retention guarantee. The most important constraints are front-loaded, and there is no wasted wording.

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 mutation profile, async behavior, cost implications, and interaction with sibling tools, the description covers all needed aspects: what it does, when to call it, how to get threadId, what to do after the call, and that changes are lossless. The output schema covers the return value, so nothing further is needed.

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 description adds meaningful semantics: prompt is interpreted with thread context, so phrases like 'the same but darker' work without repeating the original, and threadId comes from check_generation's result for start_frame. This clarifies usage beyond the raw parameter 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 states a specific verb action ('Ask for a changed version of a frame') and identifies the resource as an existing design thread, with concrete examples like 'darker' and 'make the flowers smaller'. It clearly distinguishes this tool from siblings such as start_frame (creating) and check_generation (polling).

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 the tool ('ONLY when the operator asks for a change'), when not to use it ('never iterate on your own initiative'), where threadId comes from, and directs the agent to call check_generation for the resulting preview. The cost warning provides a clear reason for the constraint.

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 goes beyond the annotations: it explains the non-idempotent behavior concretely ('saving the same generation twice makes two frames, so do not retry a call that may have gone through'), the privacy default ('private to the account unless explicitly asked to share'), and the lifecycle limitation (no edit/delete tool). Annotations already flag idempotentHint=false, but the description adds actionable consequences.

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 essential information. The core action is front-loaded, the critical warning about duplicate saves is placed early, and the final sentence addresses scope boundaries. No filler or redundancy.

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

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

For a creation tool with an output schema, the description is complete: it covers side effects, privacy, booth assignment, non-idempotency, and the absence of edit/delete tools. An agent has all the context needed to invoke correctly and set expectations.

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 provenance beyond the schema: it tells the agent that threadId and generationId come from check_generation, and that name should use the operator's words if provided. This connects parameters to the workflow, which is meaningful additional 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?

The description states a specific verb and resource: 'save one generation... as a real frame in this operator's frame list, with its photo windows cut out.' It clearly differentiates from siblings like check_generation, refine_frame, and start_frame by naming the exact output and context. An agent can tell this is the frame-creation step, not a preview or edit.

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 says 'Call it only when the operator has chosen a result' and instructs to pass the threadId and generationId returned by check_generation. It also states what this tool does not do: it does not assign the frame to a booth, and no tool edits or deletes frames. This gives clear when-to-use and when-not-to-use 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?

Beyond what annotations already reveal (mutation, non-idempotent, non-destructive), the description discloses the async job-id behavior, the need to poll via check_generation, the cost of 1 of 3 full generations per call, the 10-drafts-per-hour rate limit, and that every call creates a brand-new draft. No statement contradicts 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 every sentence carries necessary operational information: the design scope, the pre-call gathering step, async completion, draft semantics, generation cost, rate limit, and the correct sibling for changes. It is front-loaded with the primary function and then flows logically through the call lifecycle.

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—asynchronous generation, quota consumption, rate limits, draft versus final state, and multiple sibling relationships—the description covers everything an agent needs to call it correctly and safely. The output schema handles return values, so the description does not need to explain those.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond field names: it instructs the agent to gather occasion/business, vibe/style, colours, and language before composing the prompt, and warns against naming brands, characters, or franchises because the image model refuses them. This materially improves prompt quality beyond the schema alone.

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: 'Design a complete photobooth...' and enumerates exactly what the Studio produces (welcome screen, background, colour theme, capture mode, title, link name). It also distinguishes itself from siblings by clarifying the result is a DRAFT, not a finalized booth, which separates it from create_booth and refine_booth.

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-call guidance: gather in chat what /new would ask, put all of it in the prompt, then call check_generation and wait for done before treating the booth as designed. It also gives exclusions and alternatives: never call speculatively or twice, use refine_booth for changes, and use create_booth to bring the draft into the operator's booth list.

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?

Adds substantial context beyond the annotations: the call is asynchronous and returns a job id, the result is only a preview, nothing enters the operator's frame list until save_frame, and each generation consumes the account's free daily allowance. This goes well beyond the readOnly/destructive hints already provided.

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 carries operational value—purpose, asynchronous behavior, persistence path, refinement path, and cost warning. It is front-loaded with the tool's core purpose and then layers critical caveats in a logical 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?

For a complex async generation tool, this description covers the full lifecycle: initiation, result checking, refinement, persistence, and cost implications. The output schema covers return details, so nothing needed to call and handle this 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?

Although schema coverage is 100%, the description enriches the parameters: it clarifies that prompt should be in the operator's own words and not include brands, explains layout meanings including the 'strip-3' default expectation, and notes that the Studio picks the closest shape when a layout doesn't support the requested one.

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: 'Start designing a new photo frame' from a description of the desired look, and clarifies it 'opens a design thread and makes the FIRST version.' It clearly differentiates itself from sibling tools like check_generation, refine_frame, and save_frame by naming each one's role in the workflow.

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 routing: call check_generation to see the result, call refine_frame with the threadId to change a result rather than starting again, and call save_frame to persist. It also gives negative guidance—do not call speculatively, twice for the same request, or while another generation is running.

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 declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavior: what it sets lands only at create_booth time, that it 'never touches a booth that already exists', and that partial failures come back as applied/rejected that must be relayed as a rejection rather than success. This is non-obvious operational detail an agent could not infer.

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?

Dense but front-loaded: the field enumeration comes first, then the routing condition, then exclusions, then return behavior. Every sentence earns its place, though the opening enumeration is long enough to be a little heavy for a single unbroken paragraph.

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

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

For a 13-parameter mutation tool with nested settings, the description covers scope, trigger, exclusions, partial-application semantics, and return handling even though an output schema exists. Nothing material an agent needs before calling 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?

With 100% schema coverage the baseline is 3, but the description goes further: frameIds/filterIds replace the draft's list, aiEffectTitle as an empty string removes the prior effect, and the slug is availability-checked ('a taken one is reported, not stored'). These add semantics beyond the schema text.

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+resource ('Change a booth draft') and then enumerates exactly which settings it covers, so the agent knows the scope without opening the schema. It is clearly distinguished from refine_booth (AI welcome art) and from dashboard-only concerns (prices/packages).

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: 'Use it after check_generation shows the draft and the operator asks for one of these', plus two named exclusions with alternatives ('cannot change... use refine_booth', 'prices or packages are set in the dashboard'). When-to-use and when-not-to-use are both present.

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