Kelpo

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

Goes well past the annotations: debits every shot at once atomically, queues in parallel, server checks each shot then assembles/edits/delivers in conversation, failed shots are auto-refunded, and the request is rejected before any charge if English directions are missing. These are exactly the credit-safety and failure-mode facts an agent needs and that readOnlyHint=false / destructiveHint=false do not convey.

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

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

Front-loaded with the atomic-charge and delivery behavior, then preconditions, then failure/retry rules — a sensible order with no filler. The trailing pasted argument JSON restates the schema shape and is the one portion that could be dropped.

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 charging, multi-object, nested-payload tool with no output schema, the description covers authorization (confirmed/rights_confirmed), cost (max_credits equals the shown total), refusal conditions, idempotent retry, refunds, and where the result appears. Nothing essential for a correct invocation 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?

Top-level schema coverage is low and path/body carry no descriptions, but the description supplies real semantics: confirmed must follow user approval of the displayed total, max_credits must equal that total, idempotency_key is for safe retry after timeout, english is keyed per shot number. It does not mention quality or resolution, though those are documented inside the schema, so it stops short of full coverage.

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

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

States a specific verb and resource — accepting an entire multi-shot plan in one atomic confirmation — and immediately distinguishes it from the per-shot generate path and from kelpo_get_shoot, which is referenced as the prerequisite lister. An agent can tell exactly what this does and what it is not.

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 concrete preconditions and alternatives: only after the user approved the displayed total with confirmed=true, reuse the same idempotency_key on timeout, and if kelpo_get_shoot reports english_directions_needed the call is refused unless english is supplied. It also routes the rights check to the same rule as generate (rights_confirmed), so the when/when-not logic is explicit.

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 behavior, so the safety profile is covered. The description adds useful non-annotation context: the actors are fictional, photo URLs should be inspected for physical traits, and no rights declaration is required.

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 purpose and usage are front-loaded, and the text is dense but mostly earned. The arguments JSON example is useful, though the single long paragraph could be structured more cleanly.

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 with annotations and no output schema, the description covers what the catalog returns, how to use an actor, and the rights policy. It could say more about whether results are paginated or how lang filters the catalog, but it is largely complete for an agent 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?

The description supplies a concrete arguments example, which helps with invocation. However, it does not add much semantic detail beyond the schema, which already documents client_id as a workspace ID and lang as an ISO language code; the example largely repeats what the schema conveys.

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 — list ready-to-use fictional actors — and immediately contrasts them with real people. It also enumerates the returned fields, so an agent knows exactly what this catalog provides.

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 concrete workflow guidance: propose 2-3 actors by name and pass the chosen id to kelpo_expert_prepare with source catalog. It also says no rights declaration is needed, which is valuable context, though it does not explicitly mention when not to use this versus kelpo_list_people.

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 declare the generic mutation profile (readOnly=false, destructive=false, idempotent=false). The description goes well beyond them: it states that accept regenerates ONLY the listed shots, re-assembles and re-edits automatically, and that the previous version stays in Mes vidéos. That retention detail meaningfully clarifies the non-destructive annotation.

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 purpose, then enumerates accept/decline consequences in a compact single paragraph. The trailing 'Arguments:' JSON snippet is somewhat redundant with the schema but does give a quick call shape. Generally tight with little waste.

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 mutation tool with no output schema and heavily nested inputs, it covers the essential behavior: what accept triggers, that prior versions are preserved, and the credit-approval gate. Failure modes and the idempotency/offer_id mechanics are left to the schema, so it is strong but not fully self-sufficient.

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?

Top-level schema coverage is 0%, so the description carries the burden and does explain the path shape (id, shoot_id) and the meaning of decision plus the confirmed=true requirement. However it omits offer_id, idempotency_key, max_credits and the english directions object, which the agent must discover elsewhere. Partial compensation warrants a 3.

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: answering the 'fix offer' of a delivered multi-shot video, with the two possible decisions spelled out. It clearly describes what happens on each path, so the action is unambiguous. It does not, however, explicitly differentiate itself from siblings like kelpo_accept_shoot, so a 4 rather than 5.

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 clear conditions for each branch: accept only after the user approved the offer's credits and with confirmed=true; decline leaves the video as is. That is a genuine usage prerequisite for a consequential action. It stops short of naming alternatives or when-not-to-use this tool versus other offer/shoot tools, so no 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by stating that no purchase is ever performed and the agent must relay buy_url, plus signals like `low` and `expires_next` that affect what the user should be told. It doesn't mention auth requirements or how stale the balance is, so 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 core verb and the most operationally important content (credits, buy_url) before the parameter note. The parenthetical field list is dense but every item is a return value the agent may need to report; only the explicit argument echo at the end is slightly redundant with the schema.

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, so the description carries the return-value burden and does so for credits in detail; the other sections (usage, limits, keys, storage) are named but their field shapes are not, which is a modest gap. For a zero-required-parameter read tool, however, an agent has enough to call it correctly and interpret the most decision-relevant output.

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 nested `query.language` parameter is documented in the schema, but the description adds the intent behind it — it changes the account language when the user requests it — which the schema alone does not frame as an action. It also implies the argument shape ({"query": {"language": ...}}) inline, disambiguating the nested object.

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

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

Opens with a specific verb+resource ("Read the account") and enumerates exactly what comes back: credit balance, usage, limits, keys, storage, language. No sibling tool touches account state, and the description makes the scope unmistakable 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 an explicit trigger for the only parameter ("Pass language=\"en\" or \"fr\" ... when the user asks") and an explicit behavioral rule for credit purchases ("Kelpo never buys credits by itself: give the user buy_url"). It does not name an alternative or an explicit when-not-to-call, but for a unique account-read tool there is no real alternative.

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

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

Annotations only say it writes, is not idempotent and is not destructive; the description adds substantive behavior: all-or-nothing atomicity, a `receipts` structure with rejected status plus code/message for diagnosis, the fact that the message/attachments/response exchange is persisted, and safe retry via identical request_id/body after a timeout. That is well beyond annotation coverage. It stops short of describing latency, ordering constraints among operations, or what a partial rejection means for the rest of the plan.

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 verb and atomicity guarantee, then behavior, then a payload example — a sensible order with no filler sentences. The parenthetical op enumeration is dense and the trailing JSON blob partly repeats schema structure, but for a 39-way op union the example earns its 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 a 2-parameter tool whose body is a discriminated union of 39 operations and no output schema, the description covers purpose, atomicity, failure handling via receipts, and non-charging. The per-op detail lives in the nested schema descriptions, which is appropriate. Missing: no pointer to kelpo_operations_catalog for the op vocabulary, and no explanation of version conflicts.

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?

Top-level schema coverage is 0% (path.id is undocumented), but the description compensates with a concrete payload example that reveals the nested shape: path.id, body.version, body.message as the person's exact words, and an operations array with op/args pairs. That is meaningfully more than the schema alone conveys at the top level. It still leaves `version` semantics, `response` and `attachments` unexplained, so compensation is partial.

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?

Specific verb + resource: "Apply one conversational turn atomically", followed by an enumeration of the operation families it carries (classify uploads, edit scene, preparation answers, actors/outfits/voice, ask_user). It also draws a line against generation ("generation stays an explicit user approval (quote + generate)"), so the agent can tell it is not the generate tool. It never contrasts itself with siblings that duplicate the same operations (e.g. kelpo_answer_offer, kelpo_set_ai_label), so differentiation is partial rather than complete.

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?

Usage is implied rather than stated: the atomic-per-turn framing plus the retry note tells an agent this is the batching entry point, and the "never generates or charges" sentence is a genuine when-not with an alternative. But there is no guidance on routing between this umbrella tool and the many sibling tools that expose the same actions as standalone calls (offer answers, AI label, editing plan), leaving a real selection 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?

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds meaningful behavior beyond that: originals are kept, there is no generation and no charge, rights are confirmed only before generation, and new voice references need 60 seconds total. It does not state the return shape or how failures behave, so it stops short of a 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?

The core constraint sentences are front-loaded and dense with information. The final 'Arguments: {…}' JSON mirror of the schema is redundant with structured data and the 2–12 bound is repeated, which costs it 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 nested-body mutation tool with no output schema and 0% schema description coverage, the description does substantial work: it explains ordering, limits, idempotency, credits, and voice-reference eligibility. It is incomplete only on the undocumented 'consent' and 'version' fields and on error/return behavior.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it partially does: it explains asset_ids ordering, the 2–12 bound, the mandatory idempotency key, and the use_as_voice/person_id linkage. But the 'consent' flag and 'version' field are never explained anywhere, and the trailing 'Arguments: {...}' block merely echoes the schema structure without 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?

Specific verb+resource: 'Concatenate 2–12 owned audio assets in asset_ids order, keeping every sample and the originals.' The scope (owned, ordered concatenation, originals preserved) is stated precisely enough that an agent can distinguish it from generation tools like kelpo_generate and from editing tools in the sibling list.

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 real usage constraints (idempotency key required, no charge, 2–12 items, 60-second total for new voice references), which is more than generic guidance. However it never names an alternative tool or an explicit 'do not use this when…' condition, so the agent must infer routing from the sibling 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?

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds real operational context beyond that: the catalog's `value` is consumed verbatim by set_camera without English translation, and it is meant to be surfaced/offered to the person rather than invoked blindly. It stops short of describing pagination or catalog size.

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 resource and its contents, then usage guidance, then wiring, then arguments — a sensible order with no filler sentences. It is a dense run-on paragraph that mixes return-value description with invocation instructions, costing a point versus a cleanly structured definition.

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, yet the description names the returned fields and explains how the returned `value` feeds set_camera, which is the key information for acting on results. Minor gap: it lists 'id, name and description' as the contents but then refers to a `value` field that isn't included in that enumeration.

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?

Top-level schema description coverage is reported at 0% (the `query` object itself is undocumented), and the description only restates the argument shape rather than adding semantics. However, the nested lang and client_id properties do carry their own descriptions (person's language fr/en, workspace ID), so the schema still does most of the work — baseline 3.

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 resource (Kelpo's camera movements) and enumerates the returned fields (id, name, description in account language, short preview video), so an agent knows exactly what this list contains. It doesn't explicitly name or contrast against the adjacent catalog siblings (kelpo_actor_catalog, kelpo_outfit_catalog), but the resource is 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?

Explicit when-to-use ('Propose one only when the person wants a particular movement') and when-not ('otherwise choose yourself'), plus two concrete downstream invocation paths (set_camera with mode custom, and kelpo_expert_prepare camera with mode move). This is exactly the routing guidance an agent needs.

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?

Goes beyond the annotations by disclosing atomicity ('asset creation and completion commit together'), duplicate-free return, and that rights are confirmed before generation. The retry-safety claim overlaps with idempotentHint=true, but the transactional semantics add real information the annotation cannot convey.

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

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

Front-loads the verification step and the idempotency guarantee before the argument example. Dense but each sentence carries distinct information; the trailing argument JSON slightly duplicates the schema but is compact.

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 nested parameter, mobno output schema, and clear annotations, the description covers what the tool does, what it returns on retry, and the absence of a binary payload. Nothing essential to correct invocation 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 0%, so the description must compensate, and it does: it spells out the nested shape ({"path": {"upload_id": ...}}) and clarifies that the value comes from the upload ticket. It does not state constraints such as format or lifetime of the upload_id, but the nesting ambiguity is resolved.

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?

Names specific operations (verify size/MIME/SHA-256, then import) on a specific resource (reference upload), which is far more than a restatement of the name. It does not name the sibling kelpo_request_reference_upload that presumably issues the upload_id ticket, so the pairing is only implied.

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 retry guidance ('Retry the same upload_id safely') tells the agent one important usage condition, but there is no explicit statement of when to call this versus kelpo_request_reference_upload or what precondition (a valid ticket) must hold before calling.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the agent knows this is a non-destructive, non-idempotent write. The description adds that the returned id is reused downstream, but gives no auth requirements, rate limits, or side-effect detail beyond that.

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 purpose, then the dependency note, then the argument shape. The JSON argument snippet is slightly clunky with escaped quotes but earns its place given zero schema description coverage.

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?

There is no output schema, and the description does state the key return value (an id usable as client_id elsewhere). For a single-parameter create tool this covers the essentials, though the optional notes parameter and any error behavior remain 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 0%, so the description must compensate. It documents the required 'name' argument with an example body, but omits the optional 'notes' field entirely, leaving one of two properties undocumented in both schema 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?

States a specific verb and resource ('Create a workspace for a person or brand') and clarifies the entity is a client by tying it to client_id. This distinguishes it from siblings like kelpo_list_clients. Minor friction from the 'workspace' vs 'client' terminology mismatch, but the intent is clear.

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?

Explains the dependency relationship: the created id feeds kelpo_create_project, kelpo_actor_catalog and kelpo_outfit_catalog, which tells an agent this is a prerequisite step. No explicit when-not guidance, but the placement context is 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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds genuinely useful behavior by disclosing the return values (id and project_version with version 0), which is not covered by any output schema. It does not mention auth requirements or side effects on the workspace.

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?

Short, but the fragment 'body client_id' is garbled and the trailing full JSON argument dump is redundant with the schema, adding noise rather than front-loading meaning. The useful return-value info is buried mid-sentence.

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 creation tool with no output schema, the description does cover the essential return shape and argument. It still leaves the project/conversation terminology, optionality of client_id, and authorization context unexplained.

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 0% and there is one optional parameter with no schema description. The description compensates partially by naming the client_id field and giving a JSON example invocation, but it never explains the field's meaning or what happens when it is omitted.

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 ('Create') and resource ('a conversation (one video) in a workspace'), and distinguishes itself from read siblings like kelpo_get_project. However, the tool is named create_project while the description calls the resource a 'conversation', which introduces a naming mismatch an agent must reconcile.

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 no when-to-use guidance, no prerequisites, and never mentions alternatives such as kelpo_create_client or how this differs from other creation flows. The agent must infer usage entirely from the name and description.

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?

Goes well beyond the annotations: discloses atomicity ('the same operations and validations as the studio chat are applied atomically'), the outcome semantics ('status ready = recap ready; rejected = nothing saved'), the error payload shape (`problem.section` / `problem.message`), and that it neither generates nor charges. That is precisely the non-obvious behavior (no billing, nothing persisted on rejection) an agent needs before calling a mutating-but-non-destructive 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?

Purpose and prerequisites are front-loaded, but the core is one very long sentence with deeply nested parentheses ('who appears — catalogue actor, library person or a new person with 1-5 uploaded photos —, outfit, place, ...') followed by a large raw JSON blob, which is dense to parse. It is information-rich rather than wasteful, but structure could be broken into scannable clauses.

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 nested generator-scene payload with no output schema, the description covers the required workflow (upload first, call once), failure semantics and the downstream steps. The only real gap is that the returned recap/ready payload is only described indirectly via `status` and `problem.section`, but the atomicity framing largely compensates.

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?

Top-level schema coverage is 0% (the two top-level params path/body carry no descriptions), but the nested definitions are richly described, and the description supplies a concrete end-to-end body example showing version, dry_run, kind, actors with catalog_id+wardrobe, lines with who/text, location, product_ids and camera. The `dry_run: true` in the example implicitly signals a validate-first pattern that pairs with the schema's dry_run field, adding real usage value over the schema text 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?

States a specific verb and resource ('prepare the whole scene') plus a clear scope distinction: 'Espace Expert in one call, without conversation', which separates it from the conversational studio path and from kelpo_apply_operations. The parenthetical enumerates exactly what the scene is composed of (actors, outfit, place, products, lines/seen, voice, camera, music, format), so an agent knows what this tool builds 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 an explicit ordering precondition ('Upload the files first to this conversation (role unassigned, project_id), then call this once') and an explicit postcondition ('Never generates nor charges: then quote and generate as usual, after the user's approval'), implying kelpo_quote_scene/kelpo_generate come next. It does not say when to prefer this over the chat/operations route or when a free `scenario` should win over `lines`, so alternatives are only partly addressed.

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 annotations: no re-render occurs, saving consumes get_editing montage_price credits unless the version was already rendered, and sharing is a separate decision. Annotations cover the safety/idempotency profile, but the cost and no-re-render behavior is valuable non-duplicated context.

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 action and the key precondition, then cost behavior. The trailing inline Arguments blob largely repeats the input schema, which is minor waste but not damaging.

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 mutation tool with no output schema and no annotations describing returns, the description covers trigger conditions, cost, and the sharing boundary. It omits what the call returns or what state results after finalization, a small gap.

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 0% schema description coverage, the description carries the burden and largely does: it explains confirmed as explicit user approval, version as the editing version, and job_id as the optional chosen preview. It does not clarify the id format or version semantics beyond naming them.

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: save/finalize an existing preview. The workflow role is clear and it is distinguishable from siblings like kelpo_preview_editing and kelpo_get_editing. It does not explicitly name a sibling alternative, so it stops short of a 5.

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 a precondition (explicit user approval, confirmed=true) and a boundary (sharing remains a separate explicit decision). It does not name alternative sibling tools for the same workflow, so not a full 5.

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

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

Annotations only say it is a non-read-only, non-destructive write with no idempotency guarantee; the description adds far more — the 402 credits_required shape with 3 packs and buy_url, the rights/terms refusal codes, the returned credits balance structure, and the retry rule of reusing the same idempotency_key and quote_id after a timeout. No contradiction with idempotentHint=false: the client-supplied key is exactly how a non-idempotent call is made safe to retry.

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 first sentence front-loads the verb and the idempotency retry rule is well placed, but the middle is a dense run-on of nested parentheses mixing credits, rights and error codes. The trailing raw JSON argument dump largely restates the schema.

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 nested, expensive, side-effecting tool with no output schema, the description covers the return payload ('credits' with balance, videos_5s_left, low, expires_next, buy_url, message), the failure paths, and the consent/rights lifecycle. Nothing an agent needs to call this safely and report back 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?

With reported 0% top-level schema coverage, the description compensates by spelling out the argument envelope and the meaning of confirmed, quote_id, max_credits (expressed in credits, taken from the quote) and rights_confirmed. It leaves english, quality, ai_label, resolution and max_charge_cents to the (rich) nested schema, so the marginal value is real but not 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?

States a specific verb and resource — "Create one approved video and return its job ID" — and ties it to the approval precondition (confirmed=true after price approval), which cleanly separates it from kelpo_quote_scene (quoting) and kelpo_get_job (polling). An agent knows exactly what this call produces 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 explicit preconditions ('after explicit price approval', quote_id and max_credits come from the quote) and explicit when-nots: 'Kelpo never buys credits by itself', rights_confirmed=true only after the user declared rights, 'already declared files need nothing', and 'never announce a launch from an error response'. It also routes to siblings (kelpo_quote_scene / kelpo_input_requirements) for the requirement lists.

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 safety is covered. The description adds real value beyond them: it is a polling endpoint and a failed render refunds montage credits — a side effect an agent would otherwise not know.

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 returned fields, then the workflow in one sentence, then the refund caveat. The inline argument JSON is redundant with the schema, but everything else is tight and 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?

No output schema exists, and the description compensates by enumerating the returned fields. Polling cadence and error/refund behavior are addressed, leaving only the identity of the 'id' parameter underspecified.

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

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

Schema description coverage is 0% for the single nested required parameter, so the description should carry the burden. Instead it merely re-serializes the schema as {"path": {"id": "<id>"}} without saying what the id identifies (editing job? project?) or where to obtain it.

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

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

States a specific verb (read/poll) and the exact resource contents: selected sources, measured durations, version, plan, status, result_job_id. It reads as the status/result accessor for an editing job, distinguishable from generic siblings like kelpo_get_job or kelpo_get_project, though it never explicitly contrasts itself with them.

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 lifecycle guidance: poll this after render_editing and hand the result to video_download. That is clear when-to-use and what-comes-next context. The only weakness is that 'render_editing' is not in the sibling list, so an agent may not be able to resolve that reference.

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, and non-destructive behavior, while the description adds that polling is free and lists the returned job fields. It could go further on failure/retry semantics, but the key behavioral context is present.

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 status fields, followed by workflow guidance and argument shape. The sentences are dense but every part contributes useful invocation context.

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?

There is no output schema, but the description enumerates status, progress, duration, and error, which is enough for an agent to understand the return. Annotations and the provided argument form cover safety and invocation needs.

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

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

Schema description coverage is 0%, but the description compensates by showing the exact nested argument shape: path.id. It does not separately define the id beyond job context, but the surrounding purpose makes that sufficiently clear.

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: read a video job. It enumerates the status values and job fields, making the tool's scope immediately clear and distinguishable from generation/download 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?

Explicitly says to poll after kelpo_generate and before kelpo_video_download, and notes there is no need to wait before launching another take. This gives both sequence and when-not-to-block 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds modest value by disclosing the returned entities and explaining that project_version is 'the version every scene call carries' — useful domain context, but no notes on auth, size or pagination.

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

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

A single sentence, so nothing is padded, but the trailing 'Arguments: {...}' restates the schema verbatim and dilutes the otherwise dense field list. Front-loading is fine; the redundant schema echo costs it.

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 no output schema, the description correctly enumerates what is returned, which is the main thing an agent needs. However it omits any usage context or guidance against sibling getters, so it is adequate rather than complete.

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

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

Schema description coverage is 0% and the parameter is a nested object, so the description must carry the meaning. It does clarify that the nested id is a '<project id>' and even shows the literal argument shape, but that largely mirrors the schema rather than adding syntax, format or constraint detail.

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?

It names the resource (a project) and enumerates exactly what is read: scene brief, selected files, preparation state, jobs, messages, project_version. But the leading frame 'Read a conversation' is an odd/misleading label for a get_project tool, and nothing distinguishes it from siblings like kelpo_get_editing, kelpo_get_job or kelpo_get_shoot.

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?

No statement of when to call this versus the many other get_*/list_* siblings, and no prerequisites or context. The agent is left to infer that this is the project-root read.

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, so the bar is lower; the description still adds real value by noting it is 'Free' and spelling out what the response contains (status received/analysed, answer, verdict per item). It does not mention auth or rate limits, but the core traits are covered.

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?

Compact and front-loaded: what it returns, cost, then arguments. The trailing JSON snippet is slightly redundant with the schema but serves as a quick usage hint, so there is little waste.

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 annotations covering safety and no output schema, the description usefully enumerates return fields, so it is largely complete for a read tool. It falls short on the ambiguous path.id semantics, which an agent needs in order 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 0%, so the description should carry parameter meaning. Instead it merely restates the shape ({"path": {"id": "<id>"}}) without saying what the id identifies (report id, job id, shoot id) or how to obtain it.

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

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

States a specific verb ('Read') and resource ('Kelpo's answer to a report') and enumerates the returned fields (status, answer, verdict). An agent can tell it fetches a report's answer, though it doesn't explicitly distinguish it from sibling kelpo_my_reports.

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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as kelpo_my_reports (list) versus this tool (fetch answer). Usage is only implied by 'Read... answer to a report'.

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 the description adds real behavioral context beyond them: the status lifecycle (queued/running/completed/failed), the delivered terminal state, and the montage_failed + montage_refunded failure mode. Very little is missing except rate-limit or pagination behavior, which is not applicable to a read polling call.

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 content is valuable but delivered as a dense run-on with parenthetical asides, and the core purpose is not front-loaded as a short sentence. Several clauses (montage fee, refunds, english directions) could be bulleted or ordered by workflow step.

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 no output schema, the description carries the return-value burden and does so thoroughly, covering shots, credits, totals, per-shot progress, quality report, fix offer, and the montage outcome field. Only the exact shape/nesting of those fields and the offer.id usage flow remain slightly underspecified.

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 0% and the schema titles are bare ('Id', 'Shoot Id'), but the description supplies an argument example clarifying that id is the project id and shoot_id the shoot id. That partially compensates but adds no format, constraint, or error semantics for these identifiers.

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 states a specific resource and enumerates its contents (shots with duration/credits, montage_credits, totals, progress, quality report, fix offer), which is concrete and recognizable. It does not explicitly contrast with near neighbors like kelpo_get_job or kelpo_videos, so the agent must infer when this differs from generic job 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?

It gives a clear workflow: poll after accept_shoot until status=delivered, and use accept_shoot/answer_offer when english_directions_needed is present. Missing an explicit 'do not use when…' exclusion versus sibling polling tools, so it falls short of 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context beyond that: it costs nothing ('No generation or charge') and it reads the same references/library state the studio uses, which matters for trust in the result.

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 short sentences, front-loaded with the purpose. However, the trailing 'Arguments: {"path": {"id": ...}}' restates the schema structure rather than adding meaning, spending words on redundant structure.

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

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

For a read-only, closed-world lookup with one parameter and no output schema, the description conveys the purpose and cost but leaves the returned structure (what 'required/conditional/optional' looks like) and the id's origin unspecified. Adequate but with clear gaps given no 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 description coverage is 0% and the single nested parameter is documented only as 'id: string'. The description compensates partially by clarifying the id is a project id and showing the nesting, but it gives no format or how to obtain the id.

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 (Read) and resource (required, conditional and optional inputs plus the exact questions to ask), which is concrete enough to distinguish it from generation tools like kelpo_generate. It never names a sibling alternative, so differentiation is implied rather than stated.

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?

'Uses the same selected references and library as the studio' and 'No generation or charge' imply this is a pre-flight lookup that costs nothing, which is useful context for choosing it. But there is no explicit when-to-use versus when-not, and no named alternative among the many siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful domain context (one workspace per person/brand) and, importantly, discloses the return shape (id, name) despite there being no output schema. It stops short of pagination or auth notes, but the added value is real.

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 action and followed by routing guidance. The trailing 'Arguments: {}' is slightly redundant but costs nothing and every other clause earns its place.

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

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

For a no-argument, read-only list tool whose annotations fully cover the safety profile, the description supplies everything needed: what it returns, why workspaces exist, and which sibling to use for creation.

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, which is the baseline-4 case. The description reinforces this with 'Arguments: {}', confirming no input is expected, so there is nothing further to explain.

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 ('List the workspaces (clients) of the account') and even names the returned fields (id, name). It explicitly positions itself against kelpo_create_client, so an agent can distinguish it from the sibling write tool 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 decision rule: a workspace already exists per person/brand, so 'reuse it, or create it with kelpo_create_client.' The alternative and the condition that selects it are both named, 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that this concerns a library of real persons/actors and their fields, which is useful context, but it discloses nothing about pagination or result size 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-loads the purpose effectively, but the trailing inline JSON arguments block is awkward and largely duplicates the schema. Some wording is slightly convoluted ('the person themself or actors already used').

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

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

For a simple read-only list tool with no output schema, the description identifies the resource and its fields, which is largely sufficient. It omits result-count/pagination behavior and the meaning of client_id, leaving minor gaps.

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

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

Schema description coverage is 0% and the single parameter (client_id, optional with an empty default) is undocumented. The description merely restates the schema as an inline JSON 'Arguments' snippet rather than explaining what client_id does, so it fails to compensate for the coverage gap.

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 clear verb+resource ('List the people of the library') and enumerates the returned fields (id, name, photos, voice), plus clarifies scope as 'the person themself or actors already used.' It does not explicitly distinguish from siblings like kelpo_actor_catalog, so it falls just short of a 5.

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 downstream guidance ('Use their id as person_id' for kelpo_expert_prepare actors source library), which is genuinely useful. However, it offers no when-to-use/when-not guidance or comparison against alternative listing tools, leaving usage largely implied.

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, non-destructive, and closed-world, covering the safety profile. The description adds genuinely new context: that the call is free and that results include status and answers. It still omits pagination/ordering behavior, but with annotations carrying the safety burden a 3 is appropriate.

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 very short: verb, scope, and return content in the first clause, then the cost note. The trailing "Arguments: {}" is redundant with the empty schema and earns little, keeping it just below top marks.

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

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

For a parameterless read-only list tool with no output schema, the description covers scope, cost, and the shape of the returned data (status and answers). It is essentially complete, with only minor gaps around ordering or pagination that may not apply to a zero-param endpoint.

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?

There are zero parameters and the schema is empty at 100% coverage, so the baseline is 4. The description's "Arguments: {}" is consistent with that and adds no misleading parameter claims.

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 ("List the reports") scoped to "this account," and names what comes back (status and answers). It does not explicitly distinguish itself from the sibling kelpo_get_report, so sibling differentiation is only implied by "List" vs "get."

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?

No guidance on when to use this versus kelpo_get_report or kelpo_report_issue. The only usage-adjacent information is "Free," which is a cost note rather than a when-to-use rule.

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 valuable behavioral context beyond annotations: the full list is ~100 KB, and omitting names returns only names and descriptions while passing names also returns argument schemas. This output-shape variability is not in the annotations and helps the agent plan calls correctly.

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

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

The description is three sentences and front-loaded with the purpose followed by usage and parameter format. It is appropriately sized, but the argument example is effectively repeated once in prose and again as a JSON snippet, which is a minor redundancy rather than a serious flaw.

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 low schema richness, absence of an output schema, and annotations that cover safety, the description supplies everything needed to use the tool correctly: what it returns in each mode, the size warning, the parameter format, and the downstream consumer. An agent can discover operation names by calling without names and then fetch schemas for the operations it needs.

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

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

Schema description coverage is 0% and the single nested parameter is completely undocumented in the schema, so the description must carry the full burden. It does so by explaining that names is a comma-separated list, giving the format example 'plan_video,edit_scene', stating what happens when it is omitted, and providing a concrete JSON argument example.

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 'List' and resource 'domain operations shared with the Kelpo studio', and enumerates exactly what is returned (name, description, argument JSON schema). It also explicitly connects to the sibling tool kelpo_apply_operations, so an agent can distinguish it from the apply/execute tool without reading 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?

The description gives clear context: these operations are meant to be used with kelpo_apply_operations, and it explains when to pass the names filter versus when to omit it. However, it does not explicitly state when not to use this tool or name an alternative discovery mechanism, so it stops short of the fully explicit when/when-not guidance that would earn a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds useful workflow context (propose a subset, feed ids into expert_prepare) but nothing on payload size, ordering, or rate limits beyond what annotations supply.

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 resource and its fields, followed by usage and an argument example. Dense but every clause earns its place; the embedded JSON example is slightly awkward to parse inline.

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 no output schema, the description helpfully names the returned fields (id, label, audience, image URL) and the integration contract. For a zero-required-param read tool with full annotations, this is close to complete.

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

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

The schema itself documents both nested fields (lang pattern fr|en, client_id workspace id), and the description supplies a concrete example of the argument envelope ({"query": {"client_id": ..., "lang": "fr"}}). It confirms the shape but adds no semantic detail beyond the schema's own field 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?

States a specific resource (Kelpo's outfit catalogue of ready outfit photos) and enumerates the returned fields (id, label, audience, image URL). Combined with the distinct naming versus sibling catalogues like kelpo_actor_catalog and kelpo_camera_moves_catalog, an agent can identify it 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?

Gives an explicit trigger ('when the person wants an outfit from the catalogue'), a concrete action ('propose 2-3 with their image link'), and the exact downstream integration (kelpo_expert_prepare actors[].wardrobe with mode=catalog and catalog_id). This is a full when-to-use plus how-to-chain specification.

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?

Goes well beyond the annotations (which only signal non-read-only, idempotent, non-destructive) by disclosing cost behavior ('without generation credits'), visibility/scope ('private provisional video in the same conversation'), and the async polling pattern via get_editing for status preview and result_job_id.

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 prose is front-loaded and efficient, but the trailing literal Arguments JSON largely duplicates the input schema and consumes space without adding semantics, blunting an otherwise tight definition.

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 non-destructive, idempotent mutation with no output schema, the description supplies the missing operational context (cost, ephemerality, polling for result_job_id). Remaining gap is parameter meaning, which the absent schema descriptions leave unexplained.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet the 'Arguments' blob merely restates the schema shape with one example value. It never explains what 'version' denotes, how to obtain it, or what 'id' identifies, adding little semantic meaning over the raw schema.

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

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

States a specific verb ('Render') and resource ('the current edit as a private provisional video'), and explicitly differentiates from finalize_editing, which 'saves a reviewed video in My videos.' An agent can distinguish this from all editing siblings without opening a 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?

Defines the workflow: preview is provisional and credit-free, more changes may follow, and only finalize_editing persists a reviewed video. It also names get_editing as the polling target for status, so both the use case and the follow-up path are explicit.

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?

Well beyond the annotations, the description discloses the pricing model (5 credits/s Normal, 10 HD, with concrete 5-second examples), that nothing is charged and no video starts, the exact response fields returned, and conditional relay behavior for insufficient, low_after, watermark, and rights_confirmation_required. Slight tension remains: annotations mark readOnlyHint=false while the text reads as a side-effect-free estimate, and the description never clarifies whether a quote record is created.

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?

Purpose is front-loaded in the first clause, and most sentences carry real information (pricing, conditional flags, rights gating). But it is one undifferentiated wall with nested parentheses and no separation between quoting semantics, return-field meaning, and approval-flow instructions, making it hard to scan for the next action.

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?

Because there is no output schema, the description usefully enumerates the returned fields (credits, videos_5s_left, low, expires_next, buy_url, watermark_message), which is the right compensation. What is missing is the input side: with two nested, undocumented parameters and no explanation of version semantics or quote validity/lifetime.

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

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

Schema description coverage is 0% for both parameters, so the description must carry the burden — and it does not. The trailing "Arguments" block merely restates the schema shape ({path:{id}, body:{version}}) without explaining what a project id means here or what `version` refers to (project version? scene version? what happens if stale?).

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 clause gives a specific verb and resource — quote the reviewed scene in credits — and immediately scopes it ("without starting a video or charging"), which distinguishes it from kelpo_generate and kelpo_accept_shoot. It never names a sibling explicitly, so the differentiation is implied by the negative scoping rather than stated.

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?

Usage is implied by the downstream instruction "Check generation_available and generation_blockers before requesting approval to generate," which places this as a pre-generation check. However, it never says when to call this versus kelpo_generate, kelpo_input_requirements, or kelpo_get_project, and there is no explicit ordering or exclusion.

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 (which only say non-read-only, non-idempotent, non-destructive), it discloses useful operational facts: the report is free, the Kelpo team reads every report, there is no automatic analysis, and the agent must never promise a refund or fix. It does not say what happens to a duplicate submission beyond 'not one per call', and does not describe the confirmation response.

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?

Purpose and the defect taxonomy are front-loaded, and most sentences carry decision-relevant content (batching rule, evidence requirements, no-refund policy). It is dense and run-on, and the trailing raw 'Arguments:' JSON fragment adds little over the schema.

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 nested, non-read-only reporting tool with no output schema, the description supplies timing, content expectations, human-review behavior and the follow-up sibling. Minor gaps remain: no mention of the response shape or duplicate-handling, and the kind taxonomy is left to the 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 description covers the practical payload shape ('job ids and shot, what you observed (quote values, messages, heard words) and what you expected'), which maps to the key nested fields and reinforces the quoted-evidence expectation. However, the 13-value 'kind' enum, plus 'language', 'assistant' and 'project_id', are never explained in the description, leaving real gaps at low reported schema coverage.

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

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

The description opens with a specific verb and resource ('Tell Kelpo what went wrong') and then enumerates the exact categories of defects it accepts (take defects, price/charge, contradictions, slow renders, refused features, docs). It is clearly distinguishable from the status-reading sibling kelpo_get_report, which it names.

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 timing guidance ('Send one report when the problems are known (e.g. after delivery)'), an explicit anti-pattern ('not one per call'), and routes status-checking to kelpo_get_report. An agent knows both when to call this and when to call the alternative.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description enriches this with real semantics: same idempotency key + metadata returns the same ticket while changed metadata is rejected, the upload is private and expires in 15 minutes, bytes must not transit the MCP context, and rights are only confirmed before generation. That is substantive behavioral context beyond the flags.

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?

Constraints (15-minute, private, 50 MiB, no video unless swap_source) are front-loaded, and the follow-up step is stated early. The sentence is dense and the trailing literal argument blob duplicates the schema somewhat, 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 ticket-issuing tool with no output schema, the description explains the lifecycle (request -> HTTP byte transfer -> complete_reference_upload) and the key failure/open questions (idempotency conflict, expiry, rights timing). It does not spell out what the returned ticket contains, which would be the last missing detail.

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 single top-level parameter 'body' has no schema description (0% top-level coverage), so the description carries the burden — but it does so with a concrete example payload enumerating filename, size_bytes, mime_type, sha256, idempotency_key, role, and project_id. The nested schema simultaneously documents many of these fields, so the description's marginal value is mostly in showing the assembled shape rather than new field meaning.

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 precise verb and resource ('prepare a private 15-minute image/audio upload'), including the artifact produced (an upload ticket) and its scope. It is immediately distinguishable from the sibling kelpo_complete_reference_upload, which it explicitly hands off 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?

Tells the agent the full workflow: request the ticket here, send bytes via a local HTTP tool rather than through LLM/MCP context, then call complete_reference_upload. It also names the alternative path for video (role swap_source, for kelpo_swap_person) and rules out video as a chat/editing reference. No explicit statement of when not to use the tool at all, so a small gap remains.

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 non-obvious behavior beyond the annotations: the call only produces a priced fix offer and charges nothing, with charging deferred to kelpo_answer_offer. It does not mention that a defect retake overwrites and deletes the previous take and its montage — that critical side effect lives only in the schema text.

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 prose sentence is tight and front-loaded, but the trailing raw JSON argument dump duplicates the input schema without adding meaning, taking up roughly half the description.

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 mutation with no output schema, the description covers the return ('fix offer with its price') and the deferred-charge flow. The main gap is the destructive overwrite of the old take, which the schema does cover but the description omits from the agent-facing narrative.

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 0%, so the description should carry the weight, but it only dumps the request envelope (path.id, path.shoot_id, body.shots) which merely restates the schema shape. It never explains what id vs shoot_id identify, why shots is 1-based or capped at 6, nor the crucial defect true/false distinction.

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 ('redo some shots of a delivered multi-shot video') and anchors it to a recognizable user utterance. It is distinguishable from inspection tools like kelpo_view_take, though it does not explicitly contrast with them.

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 ('The user asks to redo some shots'), a concrete example phrasing, and routes the follow-up step to kelpo_answer_offer with confirmed=true. No explicit when-not guidance is provided.

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 not read-only, not destructive, not idempotent, closed-world. The description adds genuinely useful context beyond that: no rendering cost, no charge, ordering semantics, and version-based scoping. It still omits what happens to a prior selection, whether the call blocks, and error behavior for the version mismatch implied by the non-idempotent hint.

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?

Purpose and constraints are front-loaded, which is good, but the trailing raw JSON argument dump largely duplicates the input schema and adds little for an agent that already receives the schema. Roughly half the text is redundant with structured fields.

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 non-read-only, non-idempotent mutation with nested required params and no output schema, the description covers purpose, cost, and ordering but leaves result behavior, prior-selection semantics, and the version contract unexplained. Adequate but with visible gaps.

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

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

Schema description coverage is 0% and both top-level params are required nested objects. The description partially compensates: 'up to 12 ... in order' explains job_ids bounds and ordering, and 'Uses the editing version' gestures at the version field. However, it never explains what the version integer is for (likely concurrency/optimistic locking) or that job_ids are video job identifiers, so the 0% coverage is only partly offset.

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 (select) and resource (completed videos owned by the authenticated account), plus the scope constraint of up to 12 and ordering. It is clear what the tool does, but it never names or contrasts with related siblings like kelpo_start_editing, kelpo_get_editing, or kelpo_finalize_editing, so an agent has to infer where it sits in the editing 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?

The description gives preconditions (completed videos, authenticated account, max 12) but no when-to-use guidance and no explicit alternatives among the many editing siblings. 'No rendering or charge' hints at cheap sequencing but does not tell the agent when this call is required versus skippable.

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 mutating, idempotent=false, non-destructive, closed-world. The description adds genuinely useful context beyond that: 'No charge' (billing), that the change propagates to downloads/API/review/Community copies, and the scope propagation rules. It stops short of stating permissions/auth needs, so not a 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 action, then the usage caution, then scope semantics, then a cost note. The trailing inline 'Arguments' block largely duplicates structured data, which is a small redundancy, but the prose itself is 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?

No output schema exists, but for a simple idempotency-relevant toggle the description covers action, side-effect surface, scope propagation, cost, and the explicit-request constraint. What an agent needs to call correctly is present; only permission/auth details are absent.

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 reported at 0%, so the description must carry the load, and it does: it defines shown true/false and explains the three scope values with their propagation semantics. It even restates the arguments inline. Minor overlap with the schema's own enum docs prevents a 5.

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 the specific verb pair (add/remove), the exact resource (the visible « Images virtuelles » / AI-generated mention burnt into video copies), and enumerates where it appears (downloads, API/MCP, review links, Community). An agent can distinguish it from any sibling, none of which deal with labeling.

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?

Explicit gating: 'Only when the user explicitly asks for it; never offer or add it on your own' gives a clear when and when-not. It also clarifies that scope=conversation/space extends the effect to other videos, removing ambiguity about side effects.

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, idempotentHint=true, destructiveHint=false, so the safety profile is largely covered. The description adds genuine value with 'Original videos are preserved,' which explains the non-destructive consequence in domain terms beyond the generic hint, but it omits what is actually created or mutated and any auth/ownership requirements.

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?

Short and reasonably front-loaded, but the literal 'Arguments: {...}' dump duplicates the input schema and adds no meaning, and the get_editing reference is placed after the payload rather than as a routing cue.

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 state-changing editing entry point with a nested-object parameter, no output schema, and many competing editing siblings, the description is too thin. It never explains the outcome of 'starting editing,' the next step in the workflow, or what distinguishes the 'separate version' from get_editing.

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

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

Schema description coverage is 0% on a nested object, so the description must compensate, yet it only restates the JSON shape ('Arguments: {"path": {"id": "<id>"}}'). It does not explain what the id identifies beyond an implicit connection to 'conversation,' leaving the parameter semantically opaque.

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 verb+resource ('Prepare editing') is recognizable and scoped to 'any existing conversation,' but 'prepare' is vague about what state change actually occurs. It gestures at a sibling (get_editing) yet does little to differentiate itself from finalize_editing, preview_editing, update_editing_plan, and select_editing_sources in the crowded editing family.

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 only routing hint is 'Read get_editing for its separate version,' which is cryptic and does not state when to choose this tool versus the other editing siblings. No prerequisites, no ordering guidance (e.g. relative to finalize_editing or preview_editing).

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 write-but-not-destructive, non-idempotent behavior; the description adds substantive traits beyond that — it reveals that omitted finishing touches are removed (a replace-in-full semantic), that prior clips are preserved except as requested, and that it does not trigger a planner or render. These are exactly the behavioral details an agent can't infer from the hints.

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

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

Purpose is front-loaded and most sentences carry a real rule, but the block is very dense and the trailing 'Arguments: {...}' JSON example largely restates structure the agent already receives as a full schema, which is mild redundancy. Efficient overall, but not tightly structured.

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 large nested plan payload with no output schema and rich per-field $defs descriptions, the tool-level description covers the non-obvious essentials: unit conventions, replace-on-omit behavior, clip preservation, and the approval workflow. The remaining field-level richness (panels, recipe, bonuses, music) is handled by the schema descriptions, so little is genuinely 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?

Top-level schema descriptions are absent (0% coverage), but the description compensates with high-value semantics that the structured fields do not convey: clip start/end are SOURCE seconds while finishing touches (texts, overlays, subtitles, zooms) use FINAL montage seconds, along with the speed range and the constraint that only selected job_ids are valid. The source-vs-final-seconds distinction is critical and is added here, not by 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?

States a specific verb and resource — 'Save an external assistant's structured edit plan' — and scopes it with 'without invoking a planner or rendering', which distinguishes it from generation-oriented siblings like kelpo_generate or kelpo_preview_editing. It is clearly a persistence operation on an existing plan, though it does not name a sibling explicitly.

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

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

It gives concrete workflow context: send the complete plan, show the full recap, and request explicit approval before render_editing. That establishes the precondition and ordering. What it lacks is an explicit alternative-based rule (e.g. 'use this instead of kelpo_preview_editing when...'), so it is strong context but not full when/when-not routing.

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 read-only and idempotent annotations, the description adds meaningful behavioral context: the link is private, valid for 15 minutes, and revoked with the access key. It does not contradict the annotations, though it could say more about failure modes or permissions.

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 short and front-loads the core behavior in the first sentence. The second sentence mostly duplicates the schema structure, but the overall definition remains efficient.

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 one-parameter download-link tool with no output schema, the description covers the essential purpose and link lifetime. However, it omits the meaning of the required id and any details about the returned link, leaving an agent to infer key semantics.

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

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

Schema description coverage is 0%, and the description merely restates the nested argument shape as {"path": {"id": "<id>"}} without explaining what the id identifies. It adds no semantic meaning beyond the input 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 verb and resource: getting a private video download link. This clearly distinguishes the operation from most siblings such as video listing or project retrieval, though it does not explicitly contrast with kelpo_videos or kelpo_view_take.

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 implies the tool is for obtaining a download link but gives no explicit when-to-use guidance, prerequisites, or alternatives. An agent must infer the appropriate context without help from the description.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that it returns documentation content and requires no arguments, but says nothing about output format (markdown vs. structured), size, or whether the content is static versus project-dependent.

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 core purpose and the usage rule are crammed into one run-on sentence interrupted by a long parenthetical list, so the actionable guidance is buried rather than front-loaded. It is information-dense but poorly structured; splitting the enumeration from the when-to-read rule would cost nothing and gain 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?

With no output schema, the description must characterize the return value, and the parenthetical list of topics is a partial attempt at that. However, it never states the form of the returned recipes or how an agent should apply them, and vague entries like 'English directions' and 'operations path' leave the deliverable ambiguous for a documentation tool with 34 siblings.

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?

Zero parameters with 100% schema coverage, so the baseline is 4. The trailing 'Arguments: {}' redundantly but harmlessly confirms the no-argument contract; there are no parameter semantics left to explain.

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 resource — the detailed recipes of the video flow — and enumerates the covered scenarios (UGC, app, show your work, place visit, making-of, event), so an agent knows it retrieves a reference document rather than performing an action. It does not, however, distinguish itself from sibling reference tools such as kelpo_operations_catalog, kelpo_input_requirements, or kelpo_voice_recording_guide.

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 triggering conditions: 'Read it when the server instructions point to a recipe, or first when your client does not show server instructions.' That is a clear when-to-use rule, but no when-not-to-use or routing against the other catalog/guide siblings is provided.

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 the notable fact that this returns finished/rendered videos (versus editing sources), but says nothing about pagination, auth, or scoping behavior of all_spaces.

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?

Crams three distinct concerns — return fields, sibling pointer, and a raw JSON argument blob — into one run-on line. The return fields are reasonably front-loaded, but embedding a literal argument object reads as boilerplate rather than structured 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?

With no output schema, naming the returned fields (job id, title, duration, workspace) usefully fills the return-value gap. However, for a nested-object query parameter at 0% schema coverage, the meaning of client_id and all_spaces is left entirely unexplained, leaving the definition only partially complete.

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

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

Schema description coverage is 0%, so the description carries the full burden. It merely reproduces an argument example ({query: {client_id, all_spaces: true}}) that mirrors the schema structure without explaining what client_id selects or what all_spaces changes. No semantic value is added over the raw schema.

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

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

States a specific verb and resource ('List the finished videos of the account') and enumerates the returned fields (job id, title, duration, workspace), which helps distinguish it from other kelpo_ tools. It also gestures at the adjacent montage-sources tool, giving the agent a routing signal, though the relationship is only loosely stated.

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 parenthetical '(kelpo_select_editing_sources)' implies that montage source retrieval is a different tool, giving an implicit alternative. There is no explicit when-to-use/when-not guidance, no prerequisites, and no statement of what the account scope actually requires.

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 readOnly/idempotent annotations, it discloses that the result arrives as a native image the agent must interpret, and crucially that 'Kelpo does not judge the pictures of a take for you' — a behavioral fact an agent could not infer from annotations or schema. It also flags the downstream approval gate before a retake.

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 core idea (contact sheet image) is front-loaded and most sentences earn their place by covering use and next steps. It is dense, and the `times` remark adds a small amount of unexplained detail rather than trimming.

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 no output schema, the description carries the return-value burden well by stating the result is a native image, plus it covers the judgment expectation and the retake follow-up path. Nothing essential for correct invocation appears to be missing.

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

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

The description explains that `frames` produces still frames laid out in time order (left to right, top to bottom) and the argument example shows `path` as the job id, adding meaning beyond the sparse schema. The stray reference to a `times` key that is not present in the input schema slightly muddies the picture.

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 concrete verb and resource — a contact sheet of a finished video or shot take delivered as ONE image — and its scope (frames in time order) separates it from whole-video siblings like kelpo_video_download. An agent can identify what it gets back 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?

It clearly states the intended use (look at the image yourself and judge the take, then tell the user plainly) and routes the redo path explicitly to kelpo_retake_shoot followed by kelpo_answer_offer after the user's explicit yes on price. It does not, however, contrast itself against nearby read tools such as kelpo_get_shoot.

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 establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral detail the annotations cannot: the 60-second minimum (2 minutes recommended), the no-reading rule, and the exact payload shape (instructions, tips, topics, voice_messages, accepted_formats). It stops short of noting anything about rate limits or when the guide expires, but adds solid context.

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?

Content is front-loaded with the core requirement and every clause carries information (duration, reading ban, payload fields, usage rule). The first sentence is a long run-on packing several distinct rules together, which slightly hurts scannability.

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 no output schema, the description correctly enumerates the returned fields, and with zero parameters the input side needs no elaboration. The proactive-use instruction and payload inventory give an agent everything needed to call and present this 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?

The tool takes zero parameters, so the baseline is 4 and the schema fully covers the input contract. The trailing 'Arguments: {}' merely confirms the no-argument nature rather than adding new meaning.

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 ('Get the free-speech guide for a new voice reference') and immediately defines its scope with the recording constraint. It also differentiates from siblings by noting that existing voices and recorded dialogue are separate, so an agent can place it 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?

Explicitly says when to use it ('Show it proactively before the user starts recording') and when not to ('never use it as the video's dialogue'), plus that existing voices and recorded dialogue are handled elsewhere. Both the trigger and the exclusion are stated, not inferred.

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