Deepnia

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

Beyond the annotations it discloses that the call spends the user's Deepnia credits, persists the result to their account, and is automatically refunded on failure, plus the concrete idempotency guarantee keyed on quote_id. That is precisely the cost and recovery information an agent needs before triggering a destructiveHint=true, credits-consuming operation.

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

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

Front-loads the 'use this when' trigger, then tacks on the get_creation follow-up, which is good ordering with no filler. It is slightly run-on and repeats 'Deepnia' three times in one sentence, which costs a point.

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 2-parameter, output-schema-backed creation tool, everything an agent needs is present: prerequisite, cost, persistence, failure/refund behavior, idempotency, and next step. Return values 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?

Schema coverage is 100% and both properties already document that quote_id comes from quote_image and credits is the accepted price, so the description adds little on that front. The one piece of added meaning is 'the same quote_id never charges twice', which characterizes quote_id as a de-duplication key rather than just an identifier.

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 concrete verb and resource ('makes the image') and pins the inputs to the prior quote step ('from that quote_id and credits'). An agent can distinguish this from quote_image (pricing) and create_video (different medium) 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?

Gives an explicit trigger condition ('when the user accepted the price from quote_image') and names the alternative that must precede it. It also prescribes the follow-up call ('Then follow it with get_creation'), closing the loop on the workflow.

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 a destructive, idempotent, non-read-only mutation, and the description goes well beyond them: it discloses that the call spends the user's Deepnia credits, persists the result to their account, is refunded on failure, and that repeated calls with the same quote_id will not double-charge. That billing/refund/no-double-charge context is exactly the behavior an agent needs before invoking a paid mutation.

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 trigger condition and every clause carries information (payment, persistence, refund, idempotency, next step). However, it is packed into one run-on sentence that could be broken for faster scanning.

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

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

An output schema exists, so return values need no explanation, and the description covers the preconditions, cost behavior, failure handling, and the required next call. Nothing an agent needs in order to invoke this paid mutation 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 both parameters already document that quote_id comes from quote_video and credits is the accepted price, so the description largely repeats structured data. It adds only a light reinforcement that credits are drawn from the user's Deepnia balance. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ("makes the video with Deepnia from that quote_id and credits") and immediately disambiguates from the sibling quote tools by framing it as the post-acceptance step. An agent can tell this apart from create_image/create_voiceover without opening either 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?

Gives an explicit trigger condition ("when the user accepted the price from quote_video"), names the prerequisite tool, and names the required follow-up (get_creation). Usage is fully determined with no inference needed.

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

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

Annotations already flag non-read-only, destructive, and idempotent, and the description goes beyond them by explaining the financial behavior: credits are charged from the user's Deepnia balance, a failure is refunded, and the same quote_id never double-charges. That makes the destructiveHint and idempotentHint concrete rather than abstract.

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 when-to-use clause is front-loaded and every sentence carries information (trigger, charge source, refund, idempotency, next step). The single long sentence is slightly run-on, but nothing is redundant.

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 two-parameter, credit-charging mutation with an output schema, the description covers the trigger, the billing and refund contract, the idempotency guarantee, and the required follow-up call — everything an agent needs to invoke it safely.

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 both parameters are fully described there, so the baseline is 3. The description reinforces that credits is the price the user accepted and quote_id comes from quote_voiceover, but adds no syntax or format detail beyond the schema.

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

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

The description names a specific verb and resource ("makes the voice-over") and pins it to a concrete source (the quote_id and credits from quote_voiceover), which cleanly separates it from quote_voiceover (pricing) and the create_image/create_video siblings.

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

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

It states the exact trigger condition — the user accepted the price from quote_voiceover — names the prerequisite tool, and prescribes the follow-up call to get_creation, so an agent knows both when to call it and what to do next.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=false; the description adds the multi-call polling contract and the state machine, which annotations cannot express. It does not explain the readOnlyHint=false signal, so a reader cannot tell whether repeated polling has any side effect. It also never says what check_again_in_seconds is or where it comes from.

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 opens with the triggering condition and then the return contract, before placing the call sequence and the final action in order. It is one long sentence, but each clause adds new information (states, file links, polling, sharing), with almost no repetition. It is dense but not padded.

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

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

Output schema exists, so return values do not need detailed description, and annotations cover the safety profile. The description supplies the polling loop that neither structured field can express. Remaining gaps are failure handling on the 'failed'/'refunded' states and the meaning of the check_again_in_seconds field.

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 50%: 'id' is documented in the schema and reinforced by 'the returned id' in the description, but 'type' (enum image/video/voiceover) has no description text anywhere. The enum values are largely self-evident from the sibling create_* tools, so the description compensates for the id but not for the type parameter.

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 ('returns the state of one creation'), enumerates the possible states (queued, processing, completed, failed, refunded), and says file links appear once completed. That clearly separates it from list_my_creations and the create_* siblings.

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

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

It states exactly when to call it ('when a creation was started and the user wants its result'), which prerequisite tool precedes it ('after create_* with the returned id'), and how to poll ('again after check_again_in_seconds while it is not finished'). The follow-up action (share the result link) is also spelled out, so no routing 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds the meaningful behavioral point that this is account-scoped and that affordability requires pairing it with a quote_* call. It stops short of noting any staleness or refresh behavior, but nothing essential is missing.

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

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

Two sentences, front-loaded with the trigger condition and followed by the complementary pricing tools. No redundant restatement of the title and 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?

Return shape need not be described because an output schema exists, and the description covers purpose, trigger, and the related pricing calls. It leaves only minor ambiguity around whether the balance is personal or team-level, which is a small gap for a trivial no-arg read tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a no-arg tool applies. The description correctly frames the call as requiring no input.

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 ('returns the credits available on their account') and implicitly differentiates from the quote_* siblings, which return prices rather than balance. An agent can tell exactly what this tool yields without opening the schema.

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

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

Gives two explicit trigger conditions: when the user asks how many credits remain, and as a pre-check before proposing a creation they may not be able to afford. It also names the correct alternatives for pricing (quote_image, quote_video, quote_voiceover), so the agent knows where to route price questions instead.

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 read-only, idempotent, closed-world behavior, so the description's job is to add operation-specific context — and it does, disclosing that voiceover results are paged ('a page at a time') and filtered by language and gender, and naming the returned fields. It stops short of stating default page size behavior in prose (that lives in the schema) or describing the response envelope.

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

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

Two sentences with the usage trigger front-loaded and no filler; the pricing hand-off is placed at the end where it belongs. The middle clause listing durations, formats and modes is somewhat compressed and reads as a run-on, but nothing is wasted.

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

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

For a read-only catalog tool with idempotent annotations but no output schema, the description adequately signals what comes back (models, durations, formats, modes, per-model image fields, voices) and how paging works. Minor gaps remain around response shape and whether non-voiceover types ignore the voiceover-only parameters.

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 83% and each parameter already carries its own 'Voice-overs: ...' scoping note, so the schema does most of the work. The description's contribution is consolidating that model/limit/offset/language/gender only matter for the voiceover type and that max_reference_images/start_image/end_image are per-model attributes rather than inputs — useful, but marginal beyond the schema.

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

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

The description states a specific resource and scope: the models, durations, formats, modes and per-model image fields for image/video/voiceover creations, plus model voices for voice-overs. It is clearly distinguishable from the quote_* family, though the dense compound sentence makes the core identity ('list available creation options') slightly harder to grasp at a glance than the title alone.

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 names the trigger condition ('when you need the choices for a creation before pricing it') and routes the agent away to the alternative ('Exact prices come from the quote_* tools'). That is an explicit when-to-use plus when-to-use-something-else pairing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral detail beyond that: result ordering is newest-first, each item carries state and file links, and results are scoped to this app's creations on the user's account. Pagination behavior is only implied by the before_id param rather than stated.

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

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

Two sentences, front-loaded with the use case and closed with the sibling routing, with no filler. The first sentence is dense with comma-joined clauses (media kinds, ordering, state, links) but each clause carries information an agent needs.

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

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

An output schema exists, so return values needn't be spelled out, yet the description still summarizes what comes back (state and file links). For a simple, zero-required-parameter read tool, nothing needed 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 only 33% — just before_id is documented — so the description must carry more weight. It partially compensates by naming the three media kinds (mapping to the type enum) and by stating newest-first ordering, which relates to the cursor, but it never explains limit bounds or how before_id pagination is meant to be used.

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 — lists the images, videos and voice-overs this app created on the user's Deepnia account — plus ordering (newest first) and payload (state and file links). It is clearly separable from create_* siblings and from get_creation, which it explicitly routes to.

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 an explicit trigger ("when the user asks what they already made through this app, or an earlier creation's id or link is needed") and names the alternative for a different need ("To follow a creation just started, call get_creation"). The when-to-use and when-not-to-use split is unambiguous.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world behavior, so the description's job is to add operational context — and it does: default scoping when no filters are supplied, result ordering, the fields returned, and the special behavior of list_filters. It stops short of describing pagination behavior (the offset/next_offset loop) or result-count limits.

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 trigger condition, then defaults, then the sibling routing — a sensible order with no filler. The first clause is long and comma-chained, which slightly hurts scanability, but every sentence carries 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?

No output schema exists, and the description compensates by listing the returned metrics (views, likes, comments, shares), so an agent knows what comes back. The gap is pagination: offset/next_offset is a real part of using this tool at scale and is never mentioned.

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 86%, so most parameters are already documented; the description nevertheless adds real meaning by explaining the default scoping for place and niches and by giving semantics to list_filters, which has no schema description at all. It does not clarify the difference between the 'views' and 'score' sort modes beyond the terse enum 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 and resource — lists trending videos and ads across TikTok, Instagram, YouTube and Facebook — plus the dimensions (niche, place, language), the returned metrics, and the ordering (most viral first). It is clearly distinguishable from get_viral_idea, which is named as the single-result counterpart.

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?

Opens with an explicit trigger ('when the user wants ideas from what is going viral right now'), documents the no-filter default (user's own niches and region), and routes to the alternative ('For one result, call get_viral_idea'). Both the when and the alternative are stated rather than inferred.

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 real context beyond the annotations: 'Nothing is charged' and 'a quote alone creates nothing' disclose the cost and side-effect profile, which matters for a tool whose readOnlyHint is false. There is mild tension with readOnlyHint=false (a quote presumably persists some server-side record), but the description's claim is about images and charges, not quote storage, so it is not a contradiction. It stops short of saying how long a quote_id stays valid.

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 and dense, with the key constraint ('Nothing is charged') placed early. The colon-chained phrasing makes it slightly run-on but nearly every clause carries actionable information; the closing parenthetical is mildly redundant with the earlier 'before anything is created'.

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?

Covers the full quote-then-create workflow, and an output schema exists so return values need not be explained beyond the mention of quote_id and credits. With six fully described parameters and annotations present, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so every parameter including nested reference_images is already documented. The description adds a usage hint for reference_images ('give the product photo here') but adds no format, default, or constraint detail beyond the schema. Baseline 3 is correct when the schema carries 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?

States a specific verb and resource ('gets its exact price in Deepnia credits') and immediately scopes it against what it is not ('before anything is created'). An agent can distinguish it from create_image and from quote_video/quote_voiceover 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?

Gives explicit when-to-use ('when the user wants Deepnia to make an image') and the concrete next step: show the price, then call create_image with the returned quote_id and credits. It also names the condition that selects that alternative ('once they accept'), leaving nothing 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?

Annotations declare readOnlyHint=false, destructiveHint=false and idempotent=false, which alone would leave the agent unsure whether calling this costs money or creates artifacts. The description resolves that by asserting 'Nothing is charged' and 'a quote alone creates nothing', plus the instruction to surface the price to the user before proceeding. It does not mention quote expiry or how long a quoted price is honored, which is why it stops short of 5.

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 trigger, then the no-charge guarantee, then the hand-off to create_video — the important facts come first. It is dense with colon-separated clauses and runs slightly long, but each sentence carries actionable 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?

For a 10-parameter, output-schema-bearing quoting tool, the description covers the essential agent-relevant facts: no charge, price must be shown to the user, and the quote_id/credits must be passed to create_video. Return-value structure is correctly left to the output schema; only quote lifetime is unaddressed.

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

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

Schema description coverage is 100% and each of the 10 parameters is already documented in the schema with defaults and model capability pointers. The description adds only a light gloss on reference_images ('keep the exact product/person: give the product photo here'), which largely restates the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('gets its exact price in Deepnia credits') and scopes it to short video before creation happens. It is immediately distinguishable from create_video (which makes the video) and from quote_image/quote_voiceover siblings.

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

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

It gives an explicit trigger ('Use this when the user wants Deepnia to make a short video'), states the follow-up path ('once they accept, call create_video with the quote_id and credits it returns'), and warns that a quote alone creates nothing. Both when-to-use and the alternative are named.

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

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

Beyond the annotations, the description discloses that there is no charge, that the call creates nothing, and that the output quote_id and credits must be handed to create_voiceover. That is the key behavioral context for a pricing call. There is a mild tension with readOnlyHint=false, since a quote that charges nothing reads as read-only, but the hint is plausibly conservative because the call is non-idempotent; this is a gap in coherence, not a flat 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 front-loads the usage trigger and then chains the pricing step to create_voiceover. It is dense but nearly every clause earns its place; the parenthetical about a quote creating nothing is slightly redundant with the earlier 'Nothing is charged', so it is not perfectly tight.

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

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

An output schema exists, so the description need not explain the return values, and it names quote_id and credits only where the chaining logic requires it. With 6 parameters fully described by the schema, a complete usage trigger, a no-charge disclosure, and an explicit next step, nothing an agent needs in order to call 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 description coverage is 100%, so all six parameters are already documented, including defaults, ranges, and the voice_id format. The description adds only a plain-language restatement of text and voice, with no extra format or constraint detail. The baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: it prices a voice-over in Deepnia credits, before anything is created, and it ties that price to the exact text and chosen voice. That scope clearly separates it from create_voiceover, which actually produces the audio, and from the quote_image and quote_video siblings, which cover other media.

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 says exactly when to use this tool (the user wants a voice-over and needs the price first), what it does not do (nothing is charged, and a quote alone creates nothing), and what to do next (show the price, get acceptance, then call create_voiceover with the returned quote_id and credits). The alternative sibling and the condition that selects it are named explicitly.

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