Luala

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

Annotations only declare the write/open-world/non-idempotent profile; the description adds substantial context beyond them: the operation is free, the response carries photo_id and edit prices, the two-step upload dance (PUT to the returned upload url with its headers, then re-call with the key), the HEIC-to-JPEG conversion requirement, and the consent fact that upload rules were accepted at connect time.

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 the response, then the fallback ladder — every clause carries operational meaning and nothing is filler. However, the middle sentences are long run-ons with nested colons and clauses, so a stepwise structure would have made the upload sequence easier to execute correctly.

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?

This is a complex multi-step tool with no output schema, and the description supplies exactly what is missing: what the answer contains (saved photo, photo_id, edit prices, upload url and headers, key, or the luala.app page when called bare). An agent has enough to execute every branch 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 description coverage is only 25%, so the description must carry the load and largely does: photo is the user's attached file, content_type has explicitly enumerated values (image/jpeg, image/png, image/webp), size is in bytes, and key comes from the previous answer. The three valid call shapes (photo alone; content_type+size then key; no arguments) are conveyed implicitly through prose rather than stated as a required-parameter contract.

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 ('Adds one photo to the user's My photos in Luala') plus its effect ('free, so it can be edited'), which an agent can distinguish from add_selfie and list_photos/upload_status. It also enumerates concrete use cases (old print to restore, clothes to try on, a photo to change), removing ambiguity about what belongs here.

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

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

Gives explicit routing rules: pass the attached file as photo; if that fails use the content_type+size then key flow; call with no arguments to get the page where the user adds it; and never fulfil the edit with another image tool. It does not explicitly contrast with the sibling add_selfie, so the boundary between the two photo-intake tools is left to inference.

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

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

Goes well beyond the supplied annotations (which only mark it as a non-read-only, non-idempotent open-world write): it discloses the free tier, the single-clearly-visible-face rule, the 15-selfie set limit, the accepted MIME types, the HEIC-to-JPEG conversion requirement, the two-step upload handshake, and that the user already accepted the upload rules. That is exactly the mutation, quota and consent context an agent needs before calling.

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 and stays compact for a multi-step upload protocol, with no filler sentences. The telegraphic, run-on phrasing of the upload branch ('call with its content_type ... and size in bytes, PUT the file ... with its headers, then call again') is dense and costs some parseability.

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

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

Covers the tricky parts of a nested-object, multi-step upload tool and explains what the no-parameter call returns. It does not say what a successful add returns (e.g., the created selfie or remaining quota), and there is no output schema to fill that gap, though the 'answer's upload url/key' wording hints at the shape.

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 only 25% schema description coverage, the description carries the burden well: photo is 'the file the user attached', content_type is constrained to image/jpeg, image/png or image/webp with a HEIC caveat, size is in bytes, and key comes from the upload answer. Each of the four parameters is given operational meaning the schema does not provide.

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: 'Adds one selfie to the user's selfie set in Luala, which shoots are made from', plus the hard constraint of one face and a 15-selfie cap. It does not explicitly contrast itself with the sibling add_photo, so an agent must infer the selfie-vs-photo distinction from the name and the 'selfie set' phrasing.

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?

Lays out three concrete invocation modes: pass the attached file as photo, or pass content_type plus size for a sandboxed file then PUT and re-call with key, or call with nothing to get the luala.app page. This is strong when-to guidance for each branch, but it never names a sibling tool as an alternative when the content is not a selfie.

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 that this is a read-only, non-open-world operation, so the description does not need to restate safety. It adds useful behavioral context by saying the response includes the balance, an approximate number of photos it buys, and purchase locations.

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 a single front-loaded sentence with no redundant wording. Every phrase contributes either the core resource or an additional useful facet of the response.

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-parameter, read-only tool with no output schema, the description is nearly complete because it explains the main return values. The only small gap is that 'about how many photos it buys' is approximate and does not clarify credit denomination or expiration details.

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

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

The tool has zero parameters, so there is no parameter meaning to clarify beyond the schema. The description correctly focuses on what the no-argument call returns.

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

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

The description clearly identifies the resource as the user's credit balance and adds that it estimates photo purchasing power and points to where more can be bought. It is distinguishable from the sibling photo-editing and pack-listing tools, though it does not explicitly name a sibling alternative.

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: an agent should call this when the user asks about credits, photo affordability, or purchasing more credits. There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named.

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

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

The description adds substantially beyond the annotations: the call is paid from the user's credits, max_credits must reflect the price the user agreed to, and an unanswered call may already be running, so list_photos should be checked before retrying. That is exactly the non-idempotent, credit-consuming side effect an agent needs to know, which the readOnlyHint/destructiveHint flags alone 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?

The core action is front-loaded and every sentence carries functional information: constraints, pricing source, and retry safety. It is a dense single block with parenthetical asides that could be split for easier scanning, but there is no filler.

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

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

For a three-parameter, no-output-schema mutation tool, the description covers cost handling, input constraints, and recovery from a lost response. The only gap is that it never indicates what the agent gets back or where the resulting photo appears, though the list_photos hint partially covers discovery.

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 and does: photo_id is the destination photo, with_photo_id is the source subject (not a selfie, not photo_id itself), and max_credits is the price the user agreed to, with named sources for that value. All three required parameters gain meaning not present in the bare integer 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 effect: takes the main subject from another of the user's photos and inserts it into a target photo while preserving scene, framing and light. The photo_id vs with_photo_id relationship is spelled out. It does not explicitly distinguish itself from near-siblings such as replace_background or edit, which keeps it from 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 concrete when-to-use context (a subject or person cutout works well) and explicit when-not conditions: with_photo_id may not be a selfie and may not equal photo_id. It also routes the agent to get_shoot or list_photos to obtain the agreed price and to list_photos to check whether a prior unanswered call already started. It lacks direct comparison against alternative sibling tools.

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 destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: the operation costs credits, max_credits caps the agreed price, results are fetched asynchronously via list_photos, and a timed-out call may have already started. A '3' would be harsh given that last caveat directly explains the non-idempotent hint — but it never states what happens when max_credits is below the current price, so it earns a 新冠肺炎 4-minus territory; scored 3 for the missing failure semantics.

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 front-loaded: purpose first, then mode semantics, then the price/credit rule, then result retrieval and the retry warning. The first sentence is an overlong run-on covering type=change, and the get_pack parenthetical interrupts the flow. No sentence is wasted, but tighter paragraphing would improve scanning for a 13-parameter tool.

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 costly, non-idempotent, asynchronous 13-parameter mutation with no output schema, the description covers the critical unknown: how to retrieve the result and how to avoid double-charging after a timeout. Remaining gaps are enum-level behavior of the appearance attributes and what occurs on insufficient max_credits, which are meaningful but secondary.

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 partly does: type mode semantics, text's 300-character limit, max_credits as the user's agreed price sourced from get_shoot/list_photos, and outfit/place as ids from get_pack. However, six appearance parameters (hair_colour, hair_length, makeup, glasses, beard, expression) are collapsed into 'the attributes' with no mention of the 'as_in_photos' default or that these apply only to type=change, and photo_id is never explained. Substantial but incomplete compensation.

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 ('Makes an edited copy of one of the user's photos, paid from their credits') and defines the two modes, 'change' (keeps pose/framing, alters outfit, place, light, attributes, text) and 'zoom_out' (steps back one step). It distinguishes itself from zoom_in implicitly via 'steps back', but never contrasts with siblings like reroll or try_on, so an agent must still infer boundaries. Clear purpose, short of full sibling differentiation.

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 says which type to use for which intent, where to get the price for the required max_credits (get_shoot or list_photos), and where to get outfit/place ids (get_pack of the photo's pack). It also adds an operational rule — check list_photos before retrying an unanswered call. It stops short of explicitly saying when NOT to use this tool in favor of reroll, zoom_in, or upscale.

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 annotations, the description explains the returned content and semantics: ids, labels, defaults, price per photo, and that each shot is one photo with a default selection of all. It also clarifies how the tool connects to start_shoot, which is valuable behavioral context without contradicting the annotations.

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

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

The description is two compact sentences with no wasted wording. It front-loads the resource and returned contents, then adds the key shot-selection and start_shoot integration 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 one-parameter read-only tool with no output schema, the description supplies enough detail about what is returned and how the result is used by start_shoot. There are no apparent gaps that would prevent an agent from invoking it correctly.

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

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

Schema description coverage is 100% for the single slug parameter, so the schema already defines its meaning. The description reinforces that the slug identifies a pack or mix, but adds no syntax or format details beyond what the schema provides, making the baseline score appropriate.

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

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

The description clearly identifies the resource as a pack's or mix's options and lists the concrete contents: outfit, place, light, shots, shape, attribute pickers, ids, labels, defaults, and price per photo. It is easy to distinguish from list_packs or start_shoot, though it does not explicitly name those siblings as alternatives.

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 final sentence, 'start_shoot takes these ids,' gives clear contextual guidance that this tool is used to retrieve the ids and options needed before starting a shoot. It does not explicitly state when not to use it or name alternative tools, but the usage context is clear.

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

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

Beyond readOnlyHint and openWorldHint=false, the description discloses critical behavior: photos can be ready, working, or failed; failed photos are refunded; previews appear only when no photo is working; and the tool may block up to 25 seconds before answering. This is exactly the kind of behavioral detail an agent needs to avoid misinterpreting a slow or partial 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?

The description is front-loaded with the core return shape and then adds polling behavior. It is dense but earns its length because the status, link, preview, and waiting semantics are all important. Minor improvement would be splitting the long sentence for readability.

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 does the necessary work of explaining the return payload: photo ids, statuses, links, shoot page, and conditional previews. It also covers polling and wait behavior. The main gap is that shoot_id remains semantically undocumented, which matters somewhat for this tool.

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

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

The single parameter, shoot_id, has 0% schema description coverage, and the description does not explain its expected value, format, or source. The phrase 'A shoot's photos' implies the tool is scoped to a shoot, but it adds no real meaning beyond the parameter name and schema.

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

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

The description clearly states the resource and the full returned content: a shoot's photos, each photo's id, status, app link, the shoot page, and previews of ready photos. It is specific enough to distinguish this from general sibling tools like list_photos, though it does not explicitly contrast itself with any sibling.

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 operational guidance: call again until none is working, and tell the user how many are ready each time. It also explains the built-in 25-second wait while photos are working. It does not mention when not to use it or name a sibling 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?

Beyond the annotations, it discloses credit payment, the user-agreed spending cap, preservation of unpicked settings, the differing framing effects of option groups, and the possibility that an unanswered call has already started. The no-response retry procedure is especially valuable and is consistent with idempotentHint=false.

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?

Five dense but purposeful sentences front-load the operation and then cover constraints, behavioral effects, pricing, and retry safety. There is no filler, and the length is justified by the tool's eight parameters and non-idempotent paid behavior.

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 paid transformation with no output schema, it provides enough detail to make most selection and invocation decisions correctly. It could still explicitly identify a source for photo_id, describe what a successful call returns or adds to list_photos, and clarify its boundary with edit or reroll.

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 compensates well by explaining group cardinality, the purpose and length limit of text, the behavioral meaning of each option group, and the source and meaning of max_credits. The target photo_id is only implied rather than explicitly documented, but nearly all other invocation semantics are supplied.

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 specifies the operation and resource: changing the light, camera, or look of one of the user's photos. The later distinction between scene-preserving light/look changes and framing-changing camera options clarifies scope, but there is no explicit differentiation from broader siblings such as edit or reroll.

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 clear contextual guidance on preserving a scene versus re-imagining its framing, obtaining the agreed price from get_shoot or list_photos, and checking list_photos before retrying an unanswered call. It does not explicitly say when to prefer another sibling tool or when not to use this one.

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

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

Annotations already declare this is a read-only, closed-world operation. The description adds genuinely useful domain context about pack pricing and mix composition, but it does not cover return ordering, pagination, or output shape, leaving a moderate gap.

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

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

The description is front-loaded with the core action and resource, but the pricing explanation is wordy and somewhat convoluted ('with what all of a pack's photos cost and the price of one: a shoot can be any of a pack's shots, down to a single photo'). It remains one dense sentence where clearer separation would help.

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 one-parameter list tool with no output schema, the description does well to define domain terms like packs, mixes, and pricing. However, it omits what the listing actually returns per pack and whether results are ordered or paginated, which an agent would need to use the output confidently.

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

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

Schema coverage is 100%, and the description's note about optionally returning only one use case's packs simply mirrors the schema's use_case parameter and its enum. It adds no syntax, default, or behavior detail beyond the schema 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 states a specific verb and resource – it lists photo packs and mixes – and defines what a pack and a mix are. It does not explicitly distinguish this tool from siblings like get_pack or list_photos, keeping it at 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?

The optional use_case filter is explained, implying a browse/filter usage, but there is no explicit guidance on when to choose list_packs over get_pack, get_shoot, or list_photos. Usage is only implied, not stated.

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/openWorld annotations, it discloses real operational behavior: it waits up to 25 seconds while an edit is still processing, includes previews for ready items, and notes that results are paged (5 vs 10 per page depending on mode). The 25-second blocking wait is exactly the kind of latency detail an agent needs before calling. It omits failure behavior when the wait expires and references an output field (`next`) that is undocumented anywhere.

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?

One dense run-on built from colons and dangling clauses, with the most common no-parameter case buried in the middle rather than front-loaded. The trailing example fragment ('an old print to restore, clothes to try on, something to add') adds no retrievable instruction. Content is present but structure actively impedes comprehension.

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, three-mode paginated list tool with no output schema, the description covers modes, page sizes, and polling latency, which is the right scope. It falls short by referencing a `next` field from the response that has no schema support, and by not saying what happens when the 25-second wait lapses. Annotations already cover the safety profile, so those gaps are the remaining ones.

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 all three parameters, and it does attempt to: `ids` for up to 10 specific photos, `before` as the cursor taken from the response's `next`, and `uploads` for My photos plus derived images. The coverage is broad but the phrasing is fragmented enough ('pass the answer's next as before for the five after') that an agent could misread the pagination contract, and it never clarifies what `before` actually identifies.

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 never states a clean verb+resource; it opens with 'With ids, those photos (up to 10)' and describes outputs rather than the action, relying on the title for the 'list' framing. Three distinct modes (by ids, latest shoots, uploads) are discernible, but only after the agent parses a convoluted run-on. An agent can eventually tell it apart from siblings, but not quickly.

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?

Mode selection is genuinely specified: pass `ids` to retrieve specific photos and poll an edit's result, omit everything for latest shoots, and set `uploads: true` for My photos. However, no sibling tools are named (get_shoot, upload_status, edit are plausible alternatives), and there is no explicit 'do not use this when…' guidance, so the routing is implied rather than stated.

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 non-read-only, non-idempotent, non-destructive, so the bar is lower, yet the description adds real value: the operation is paid from credits, max_credits must match the agreed price, and a timed-out call may already have started. That retry warning meaningfully reinforces the idempotentHint=false annotation. It does not say what happens if credits are insufficient or what the result object looks like.

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 action comes first, then backdrop semantics, then pricing, then the retry caveat. The long parenthetical colour list is bulky but genuinely useful given the schema has no enum. No filler sentences.

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 paid, non-idempotent mutation with no output schema, the description covers cost, backdrop options, and retry safety well, but never indicates what the call returns or how the resulting image is retrieved. That leaves a real gap for an agent that must act on 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 description coverage is 0%, so the description must carry the load, and it largely does: backdrop is explained as 'clear' or a #rrggbb colour with the app's palette enumerated, and max_credits is tied to prices from get_shoot or list_photos. photo_id is left implicit, which is a minor gap for a required 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?

States a specific verb and resource: 'Cuts the person out of one of the user's photos', and clarifies the two modes (clear backdrop vs. named colour, and re-laying an existing cutout). It does not name the obvious sibling replace_background, so the agent must infer the distinction from the sibling list rather than the text.

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 operating context: use it on a user's photo, and on an already-cutout photo it composites onto another backdrop. It also gives a concrete retry rule ('check list_photos before calling it again'). It stops short of explicitly contrasting with replace_background or stating prerequisites such as sufficient credits.

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 a non-read-only, non-idempotent, non-destructive mutation, and the description usefully builds on that by disclosing that calls are paid from credits and that an unanswered call may already have started, with concrete recovery guidance. It does not address ownership/permission requirements or what happens to the source photo, but the annotation baseline covers most of the safety profile.

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 every clause carries information, but the whole thing is a single dense sentence chain stitched with semicolons and colons. Splitting the precedence rule, the credit semantics, and the retry warning into distinct sentences would make it easier to scan under time pressure.

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 paid, non-idempotent mutation with no output schema, the description covers the two things an agent most needs: where the price comes from and how to avoid double-charging on retry. It stops short of describing the result (new photo vs. modified original) or expected latency.

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 carry the burden, and it does: text is constrained to the place name in up to 300 characters, scene refers to the app's presets, precedence between the two is stated, and max_credits is defined as the agreed price sourced from get_shoot or list_photos. Only photo_id is left implicit (as 'one of the user's photos').

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 – relocating the person in one of the user's photos to a different setting while preserving pose and framing. That framing implicitly separates it from remove_background and reroll, though it never names those siblings directly.

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?

Clear operating context: choose either a preset scene or a free-text place, and the scene takes precedence when both are supplied. It also directs the agent to get_shoot or list_photos to obtain the price and warns to check list_photos before retrying an unanswered call. It does not explicitly say when to prefer a sibling like reroll or remove_background instead.

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

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

Annotations only say this is a non-read-only, non-idempotent, non-destructive write. The description adds the critical economics: the call spends the user's credits, max_credits acts as an agreed price cap, and a no-answer call may already have started, so list_photos should be checked before retrying. That is exactly the behavioral context annotations cannot carry.

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, each carrying distinct information: what it does, how to price it, and how to recover from a timeout. Slightly dense but front-loaded and free of filler.

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

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

For a two-parameter paid mutation with no output schema and no annotations beyond hints, the description covers cost, price source, and duplicate-call risk, which are the failure modes that matter. It could still say what a successful call returns, but the essential calling information is present.

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 for max_credits: it is the price the user agreed to, sourced from get_shoot or list_photos, which explains both meaning and value provenance. photo_id is left to be inferred as the photo to regenerate.

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?

"Makes the same photo again, a new take of the same look" gives a concrete verb and resource and implicitly separates it from edit/upscale/zoom_in, which transform rather than regenerate. It stops short of naming the alternatives explicitly, so the distinction is inferable 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?

It tells the agent where to source max_credits (get_shoot or list_photos) and gives a concrete retry procedure after an unanswered call. It does not say when to choose reroll over sibling generators like add_photo or start_shoot, so sibling routing guidance is incomplete.

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 this as a non-read-only, non-idempotent mutation, but the description adds real behavior the annotations cannot: the operation is paid from user credits, price scales with size, max_credits is a price the user agreed to, and a timed-out call may already have started work. That last point is crucial non-idempotency context for an agent.

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

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

It is front-loaded with the core purpose and every clause carries information, but it is written as one very long, dense run-on, which makes the size/price and retry guidance harder to scan than separate sentences would be.

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 6-parameter paid mutation with no output schema and no annotations detail, the description covers cost, parameter meaning, sourcing of inputs, and retry safety. It does not say what a successful call returns or how to observe completion, which is the main remaining 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?

Schema coverage is 0%, so the description must carry the parameter meaning, and it does: size maps to 1K Standard vs 2K High quality with price by size, max_credits is the agreed price sourced from get_shoot or list_photos, and repair/faces/colourise are each defined behaviorally. photo_id is implicitly sourced from list_photos.

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 gives a specific verb and resource ('Repairs an old or damaged photo') and then decomposes the sub-operations (repair/faces/colourise), so an agent knows exactly what the tool does and which modes it covers. This distinguishes it from siblings like upscale or edit without needing their schemas.

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 names the intended input ('a photographed print, most often one from list_photos with uploads') and adds a retry rule: check list_photos before calling again if a prior call got no answer. What is missing is an explicit statement of when NOT to use it (e.g. versus edit or upscale for non-damaged photos).

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 (non-readonly, non-idempotent) it discloses the credit-charging model, that the request is rejected when the cost exceeds max_credits, an expected duration of about 20 seconds, and the non-idempotency hazard with a concrete remedy. That is exactly the behavioral context annotations alone 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?

Four sentences, each carrying distinct operational content: what it does, how to scope it with the user, the price gate, and runtime/retry behavior. Prerequisites are front-loaded and there is no restatement of the name or title.

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

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

For a paid, slow, non-idempotent mutation with no output schema, the description covers cost, scoping, latency, and retry safety well. The one gap is that it never says what the call returns (presumably a shoot identifier to pass to get_shoot), which the agent must infer from the follow-up instruction.

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 baseline is 3, but the description adds real meaning for max_credits as a price the the user must have agreed to and a hard refusal threshold rather than a mere integer bound. It also frames pack as priced via get_pack. The options object is left entirely to the schema, which keeps it slightly below 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?

"Starts a shoot of a pack from the user's saved selfies, paid from their credits" gives a concrete verb, resource, input source, and cost model in one clause. It also distinguishes itself from get_shoot (polling) and get_pack (pricing) by reference, so an agent can route correctly without reading 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?

It states an explicit precondition (tell the user the price first and pass it as max_credits), a conditional workflow (offer the whole pack or only chosen shots unless the user has already said), and recovery guidance (if a call got no answer, check list_photos before retrying). Alternatives are named by tool, not left to inference.

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

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

Beyond the annotations, the description discloses that the operation is paid from the user's credits, that pricing must be pre-agreed and bounded by max_credits, and that a call may already have started even when no answer came back. That async/partial-execution warning is behavior the annotations (readOnlyHint false, idempotentHint false) cannot express, and it directly guards against duplicate charges.

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?

It is front-loaded with the core action and packs constraints, pricing, and retry guidance without filler. The pricing sentence is somewhat tangled ('the photo's prices from get_shoot or list_photos name it'), which costs a point on readability but not on economy.

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 credit-consuming, non-idempotent generation tool with no output schema, the description covers cost, input constraints, and how to recover results after a failed or silent call (check list_photos). It never states what a successful call returns or how long results take, which is the remaining 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?

Schema description coverage is 0%, so the description carries the full burden, and it does: photo_id as the target person's photo, with_photo_id as the garment source (and its exclusion rules), part as an optional top/bottom selector, and max_credits as a price ceiling with a stated source. Every parameter gets meaning the bare schema lacks.

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

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

The description names a specific verb and resource ('Puts the clothes another of the user's photos shows ... on the person in one of their photos') and scopes the 'part' option to top or bottom only. This clearly distinguishes it from sibling tools such as combine, edit, or replace_background.

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 preconditions: with_photo_id may not be a selfie and may not equal photo_id, and max_credits must match the price the user agreed to, sourced from get_shoot or list_photos. It also tells the agent what to do after an unanswered call. It stops short of naming an explicit alternative tool for cases where these conditions fail, so it falls just short of 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so the trailing "Read-only" adds no information and is redundant. What the description does contribute is the staging concept: a file is staged at a key by add_photo/add_selfie and this tool reports whether that staging was saved. That lifecycle context is genuinely useful, though the description stops short of describing what state is observed or how long staging persists.

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?

It is short, which is appropriate for a two-parameter read tool, but the front-loaded phrase "For Luala's widget" delays the actual subject, and the redundant "Read-only" tail repeats an annotation. The parenthetical "(tool)" reads as an editing artifact rather than meaningful 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 simple read tool with no output schema, the description should at minimum say what the caller receives (a boolean, a status string, an error when the key is unknown). That return-value gap is the main shortfall. The upload lifecycle reference and the read-only nature are otherwise adequate for a tool of this complexity.

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 burden and does partially meet it: key is the staged file's key and tool identifies which upload path produced it. The enum values are already in the schema, so the tool parameter gains little beyond that. Neither parameter's format, expected key shape, or failure behavior is explained.

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

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

The description names the query ("whether the file staged at key was saved") but never states the outcome shape or uses a clean verb+resource formulation. The parenthetical "(tool)" and the leading "For Luala's widget" make the intent harder to parse than it needs to be. An agent can roughly infer it is a status lookup for a prior upload, but the phrasing is muddier than a simple "Check whether a staged file was saved."

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 ties the tool to add_photo and add_selfie, implying it is called after one of those upload tools, which is useful context. However, it never states when it should or should not be used, what a pending versus missing key means, or how it differs from re-querying via other siblings. Usage is implied rather than guided.

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 past the annotations by disclosing that credits are spent, that eligibility is constrained per photo, and that a failed-looking call may already have started so list_photos should be checked before retrying - exactly the non-idempotent recovery guidance annotations can't express. This is consistent with idempotentHint=false and destructiveHint=false.

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

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

Three sentences, front-loaded with purpose then constraints then failure recovery; nothing is padding. The phrase 'its prices from get_shoot or list_photos name them' is slightly convoluted and could be plainer.

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-idempotent, credit-spending mutation with no output schema, it covers cost, eligibility, and retry safety well. It never says what a successful call returns (a job, a new photo id, or the upscaled photo) or how long it takes, which matters for an agent deciding whether to poll.

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 full load and does so: size is explained via the larger-than-source and 4x eligibility rule, max_credits is defined as the user-agreed price sourced from get_shoot/list_photos rather than a raw budget, and photo_id is scoped to the user's own photos. Substantially more meaning than the bare 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 ('Upscales one of the user's photos') plus the exact output options (1K, 2K, 4K) and the payment source (credits). It never distinguishes itself from the closest sibling, zoom_in, so an agent must infer which of the two upscaling-ish tools to pick.

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 real usage rules: only sizes larger than the source and at most 4x it are offered, prices come from get_shoot or list_photos, and max_credits must be the price the user agreed to. Missing is any 'use this instead of X' routing against zoom_in or edit, and no prerequisite about how the user grants consent to spend credits.

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 non-read-only, non-idempotent, non-destructive, closed-world behavior. The description adds real context on top: the call is paid from the user's credits, and a call that got no answer may already have started, which warns against duplicate charging. It still doesn't say what is returned (e.g. a new photo id) or whether the source photo is altered.

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

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

Three sentences, front-loaded with the core action, then geometry, then pricing and retry safety. Dense and largely waste-free, though the clause 'the photo's prices from get_shoot or list_photos name it' is awkwardly inverted.

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

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

Covers cost, frame geometry and the non-idempotent retry hazard, which is most of what a credit-spending mutation needs. Since there is no output schema, the missing piece is what the tool produces or how the new photo is identified, which the description never mentions.

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 coverage the description must carry the load, and it does for the geometry: x, y, w are fractions of the photo from 0 to 1 representing left edge, top edge and width, with the largest frame centred when omitted. max_credits is explained as the agreed price and photo_id as one of the user's photos; ratio is only alluded to as 'the given shape' and is left to the enum.

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: cuts a frame of a given shape from one of the user's photos and upscales it to a full photo. That is materially more specific than the title and separates it from plain upscale, but it never explicitly names upscale/edit/reroll as the alternatives, so sibling differentiation is only implicit.

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 routing guidance: prices to pass as max_credits come from get_shoot or list_photos, and a retry should be preceded by a list_photos check. It does not state when to prefer this over upscale or reroll, which is the remaining gap.

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