Odile Labs

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

The description discloses key behaviors beyond the annotations: idempotency is explained concretely ('calling it again with the same sources returns the existing job (replayed: true)'), the credit model is clarified ('credits are only spent by unlock_job'), and the immediate return shape is described ('same shape as get_job plus replayed and next'). This adds significant context that annotations alone don't provide.

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

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

The description is dense but every sentence earns its place: it covers cost, idempotency, the one-job-per-upload rule, auth requirements, return shape, and next steps. It's front-loaded with the core action and immediately gives the most important caveat (costs nothing). No filler or repetition of schema details.

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

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

For a tool with 3 params, no output schema, and rich annotations, the description covers everything an agent needs: prerequisites (prepare_upload), cost model, idempotency behavior, auth requirements, return shape, and polling instructions. The only minor gap is that it doesn't explicitly state error cases, but the description is complete enough for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaning by explaining the relationship between sources and outputs ('One set of uploads makes exactly one job') and the replayed behavior when calling with the same sources. It doesn't add per-parameter syntax details, but the schema is thorough, so the baseline 3 is exceeded by the added semantic context.

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 ('Queue'), a resource ('an Odile Formats job'), and the source of inputs ('sources uploaded with prepare_upload's helper'). It clearly distinguishes this from siblings like unlock_job and get_job by explaining what this tool does (queue) versus what others do (unlock, poll).

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

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

The description explicitly says when to use this tool (after prepare_upload, before unlock_job), what it costs (nothing), and what to do instead if you need different outputs (upload again with prepare_upload). It also tells the agent to poll get_job until ready, providing clear routing to the correct sibling.

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 mark the tool read-only and idempotent, and the description reinforces this with 'Needs no sign-in and changes nothing.' It adds significant behavioral detail: exact pricing for photos and most video presets, the length-dependent 1-or-2 credit range for YouTube, the exact return object shape, and error behavior for invalid presets or out-of-range photo counts.

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

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

The description is dense but well-structured: purpose first, then usage timing, then pricing rules, return shape, and error behavior. Every sentence contributes distinct information, and there is no repetition of schema 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?

With no output schema, the description fully covers the return value, including minimum_credits, maximum_credits, final_price_known, charge_now: 0, and why. It also covers prerequisites, side effects, authentication needs, and error cases, making the tool fully callable without additional investigation.

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

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

Although schema coverage is 100%, the description adds real meaning beyond the schema: it explains which output presets cost exactly 1 credit and why YouTube may cost 1 or 2. It also clarifies that photo_count failures produce errors naming valid values, giving the agent useful expectations for that parameter.

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

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

The description uses a specific verb ('Price') and resource ('an Odile Formats job in credits'), and immediately distinguishes the tool from the follow-up unlock_job by saying it runs 'before anything is uploaded or charged.' This makes its role unambiguous even among many sibling tools.

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

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

It states exactly when to use it: 'to tell the customer the cost and get their approval before unlock_job.' It also names get_catalog as the source of valid preset values, giving the agent an explicit alternative for validation. This is strong usage 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds what they cannot: it requires a signed-in connection, takes no arguments, changes nothing, and documents the exact return shape including edge cases (credits is 0 when empty, next_expiry is null when none).

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 purpose, then usage, then return contract, then the buy path. Dense parentheticals make it long, and the buy_pack/buy_credits_at passage drifts toward documenting a sibling, but every clause carries actionable information.

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

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

With no output schema, the description must supply the return contract, and it does so fully (account, credits, next_expiry shape, buy_credits_at). Auth requirement and side-effect profile are both covered, leaving nothing an agent needs before calling.

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, so per baseline this scores 4; there is nothing for the description to disambiguate. It usefully documents the return field semantics instead, though that is technically output rather than input semantics.

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

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

States a specific verb+resource ('the signed-in customer's Odile Formats credit balance') and immediately situates it against siblings by naming unlock_job and buy_pack. An agent can tell this apart from the other get_* tools without opening any schema.

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

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

Gives explicit trigger conditions ('use it before unlock_job to check the job is affordable, or when the customer asks') and routes the alternative case ('to buy more: buy_pack') to the correct sibling, including the required billing:checkout permission.

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

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

Even though annotations already mark readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds meaningful behavioral context: no sign-in required, no arguments, no side effects, and prices are 'read from the same source the website charges from.' This goes well beyond the annotation defaults.

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

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

The description is front-loaded with the core purpose and usage guidance, then provides the complete return shape because there is no output schema. Every sentence adds value: scoping, invocation ordering, side-effect disclosure, and the exact response 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 zero-argument read-only catalog tool with no output schema, the description is remarkably complete: it states what the tool is for, when to call it, what it returns, and that it requires no authentication. It also names the sibling tools that should follow, so the agent can sequence its workflow 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?

With zero parameters, the schema provides no parameter documentation, but the description explicitly says the tool 'takes no arguments.' This matches the empty parameter list and gives the agent confidence that no input preparation is needed, satisfying the 0-parameter baseline.

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: 'The live price list and limits for Odile Formats,' and immediately scopes what Odile Formats does versus what it does not ('it does not pick clips, write captions or edit'). This clearly distinguishes get_catalog from the editing/job siblings.

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

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

It gives explicit sequencing guidance: 'Call it first, before estimate_media_job or prepare_upload, to learn the preset and fit names, the file limits and the job flow.' It also states 'Needs no sign-in, takes no arguments and changes nothing,' which tells the agent exactly how to invoke it and what to expect.

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, and the description reinforces this with 'changes nothing.' It adds valuable context beyond annotations: links expire after 15 minutes, files are kept 30 days, and an unlocked job returns an error with state and cost. It does not contradict annotations.

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

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

The description is dense but every sentence earns its place: purpose, usage timing, side-effect-free guarantee, return shape, link lifetime, file retention, and error behavior. It is front-loaded with the core purpose and then layers necessary operational details.

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

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

For a single-parameter read-only tool with no output schema, the description covers the return shape, link expiry, file retention, error behavior, and how to handle the links. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% and the schema already documents job_id as a UUID of an unlocked job. The description adds the precondition that unlock_job must have succeeded, which is meaningful semantic context beyond the schema's wording.

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 ('get signed download links'), a resource ('finished files of a job'), and a precondition ('once unlock_job has succeeded'). It clearly distinguishes from siblings like unlock_job and get_job by focusing on the download-link step.

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 use it as the last step of the flow and again when links expire, and tells the agent to call unlock_job first if the job is not unlocked. It also gives practical guidance on fetching files with curl versus giving links to the customer.

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, but the description adds substantial context beyond them: signed-in requirement, no side effects, the state machine (queued|rendering|ready|failed), the billing rule that nothing is charged until unlock_job, and the 'No such job' error for ids outside the account.

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

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

Dense but front-loaded: the core behavior leads, followed by usage cadence, then return shape and error/related-tool notes. It is longer than typical, though nearly every clause carries operational value (polling interval, billing rule, credits_cost caveat).

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 fully specifies the return shape for both modes, including field names and the credits_cost/credits_cost_known dependency. An agent has everything needed to call and interpret this tool without guessing.

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

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

Schema coverage is 100% and the schema already documents job_id, but the description adds real meaning: omitting it returns the ten most recent jobs, and an id must belong to this account or the call errors. That goes beyond the schema's UUID format 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 precise verb+resource (get one job by id, or the ten most recent), including the distinct two-mode behavior in the first sentence. It is clearly distinguishable from siblings like create_media_job, unlock_job, and get_downloads, which it names as different responsibilities.

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

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

Gives explicit when-to-use guidance (poll after create_media_job, every 10-20 seconds, up to 10 minutes, until state is ready or failed) and what to do past that window. It also names the alternative tools for adjacent needs: get_downloads for files and estimate_media_job for pricing before upload.

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 say it is a non-idempotent, non-destructive, closed-world write) by disclosing token lifetime (30 min), that each call mints a new token while earlier ones stay valid, that it needs write access, that nothing is charged, and that bytes never transit the conversation. Also enumerates the return shape.

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 headline return value are front-loaded, and every subsequent sentence carries distinct operational information (expiry, re-call policy, alternatives). No filler despite the length.

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 explicitly lists the returned fields and the per-job file constraints, and names both the upstream and downstream siblings. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single 'kind' enum is fully documented in the schema. The description's 'one video OR up to ten photos per job' restates the schema's own limits rather than adding new syntax or format meaning, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('returns a 30-minute upload token and the helper command') and frames it as 'step one of an Odile Formats job', which distinguishes it from create_media_job and estimate_media_job. An agent can tell exactly what this call produces.

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 routes: price first with estimate_media_job, file limits via get_catalog, source keys flow into create_media_job. It even specifies when to re-call ('only when a token has expired or for a new job'), covering the when and the when-not.

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 include idempotentHint=true and destructiveHint=false, and the description adds crucial behavioral context: refusal conditions (cost > max_credits, not ready, short balance), no charge for already-unlocked jobs, auth requirement ('signed-in connection with spend access'), and return shape. This goes well beyond the annotations.

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

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

Four sentences, each earning its place: purpose, precondition, refusal behavior, idempotent behavior, auth, and return value. Front-loaded with the core action and precondition, no filler or repetition of schema details.

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

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

For a 2-param tool with no output schema, the description is complete: it covers preconditions, failure modes, idempotency, auth, and return shape. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the guardrail semantics of max_credits ('The unlock is refused, charging nothing, if the job costs more') and the readiness precondition for job_id, which the schema alone does not convey. It doesn't add format details, but the schema already covers those.

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 ('Spends'), a resource ('customer's credits'), and the target ('unlock a finished job's files'). It clearly differentiates from siblings like get_job (which only reports status) and estimate_media_job (which estimates cost), so an agent can tell when to invoke this tool.

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

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

Explicitly says 'Only call once get_job says the job is ready and the customer has approved a maximum spend.' It also names the next step ('next: get_downloads') and the alternative path (get_job for status), giving clear when-to-use and sequencing guidance.

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