Pixeloa

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

Goes well beyond annotations by disclosing append-vs-position ordering behavior, the 404 cross-account condition, the specific 409 conflict causes (item not ready with details.status, not catalog-eligible, unlisted, already present), and the required write_catalog scope. With readOnlyHint=false and destructiveHint=false already given, this adds substantial operational 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?

Three tight sentences with the core action and append behavior front-loaded, followed by failure modes and the auth requirement. No filler and every clause carries information.

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

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

Covers preconditions, error taxonomy, scope requirement, and ordering behavior for a mutation tool with no output schema. Only the return/shape of the added item is unaddressed, which is minor given no output schema is defined.

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

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

Schema coverage is 50% and the description's 'appends unless position is given' is the only real explanation of the position parameter's semantics. The id and item_id parameters remain undocumented outside their types, so the description adds value but does not fully 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 specific verb and resource ('Add an item to a catalog') and immediately clarifies scope and ordering semantics ('appends unless position is given'). It is unambiguous and clearly separates the tool from siblings like removeCatalogItem and createItem.

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 (both catalog and item must belong to the key's account) and the required scope, which tells the agent when the call will succeed. It does not explicitly name an alternative tool or state when not to use this one, but the eligibility and conflict rules make the usage boundary 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely non-redundant context: the required scope, the accepted entry statuses, and the resulting 'confirmed' state. It stops short of describing failure behavior, whether confirmation is reversible, or what happens to a previously confirmed value.

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 with zero filler; the core action is front-loaded and the preconditions and permission follow in priority order. Every clause carries information an agent needs.

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

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

No output schema exists and the tool takes a nested object, so the description carries real weight — and it does supply the state machine, scope requirement, and units. Only the undocumented notes parameter and post-call/failure semantics 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 50%: id and idempotency_key are documented in the schema, while notes and the nested dimensions_cm fields are not. The description compensates for the unit ambiguity by stating '(cm)', which the schema omits, but says nothing about notes or how the three dimensions are interpreted.

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 ('Confirm the item's real-world dimensions (cm)') and immediately pins down the state transition it performs ('Moves the item to confirmed'). That is distinguishable from siblings like updateItem, startGeneration, or publishItem without opening any schema.

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

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

Explicitly names the precondition states ('awaiting_confirmation', or 'failed' with a completed analysis), the ordering constraint ('before generation'), and the required permission ('scope: confirm_scale'). This is a full when-to-use/when-not-to-use statement rather than implied 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?

Despite annotations covering only the safety profile (readOnly false, idempotent false, destructive false), the description adds substantial context: server-side fetching, https-only, provider limit checks, the 'analyzing' state transition, and the required confirm_scale follow-up. This is exactly the behavioral detail annotations cannot express.

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 constraint details, then the workflow. Each sentence contributes non-redundant information (URL hosting rules, front-view semantics, state/poll guidance, required scope), with zero 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 write-with-side-effects tool lacking an output schema, the description compensates by describing the resulting state ('analyzing') and the exact next step (poll until confirm_scale), plus auth scope. An agent has everything needed to invoke and follow up 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 only 20% schema description coverage, the description must compensate, and it does thoroughly for image_urls (1–4, first is front view, https, public reachability, no pixeloa.ai host). However, title, description, and owner_dims_cm receive no semantic detail anywhere, leaving half-plus of the parameters undocumented.

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+resource: 'Create an item from 1–4 image URLs and start analysis.' This is concrete and an agent knows the scope and that analysis is triggered. It does not, however, explicitly distinguish itself from similarly named siblings like addCatalogItem, leaving that inference to the agent.

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 operational context: the required scope 'upload_images' and the post-call workflow ('poll GET /v1/items/{id} until next_allowed_actions contains confirm_scale'). There is no explicit when-not-to-use or named-alternative guidance, so it falls 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?

Annotations already flag destructive/idempotent, but the description adds substantial context: the unpublish cascade (public page, QR, embeds go quiet), removal of item memberships while leaving items intact, clearing of the primary-catalog pointer, permanence, and the demo-catalog 409. This is exactly the extra behavioral detail the structured fields do not 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?

Front-loaded with the core action and its key side effect, then the cascading consequences. Slightly dense semicolon-chained prose, but nearly every clause conveys distinct, non-redundant information.

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

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

No output schema exists, yet the description covers auth scope, failure mode (409), permanence, and downstream effects on memberships, public page, and primary-catalog pointer. An agent has everything needed to invoke it and anticipate 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 both id and idempotency_key are already documented in the schema, including the retry semantics of the idempotency key. The description adds no parameter-specific syntax or format detail, so baseline 3 applies.

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

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

States a specific verb (delete) and resource (catalog), and the parenthetical clarifies the side effect up front. Sibling list is dominated by item-level tools, and the description makes clear this operates on a catalog rather than an item.

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

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

Explicitly states one cannot delete the platform demo catalog (409 conflict) and that the scope write_catalog is required, which are real preconditions. It does not name a sibling alternative or describe when to prefer this over, say, unpublishItem, but the conditions given are concrete.

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=true, but the description adds far more: the item is unpublished first so its AR page and embeds go quiet, images/models/QR are then removed, the change is permanent, and it alters public state. That is exactly the side-effect detail an agent needs before a destructive 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?

Front-loaded with the core action and its consequence, and the permanence and scope warnings are prominent. Slight redundancy: the unpublish-first behavior is stated in the parenthetical and then re-explained in the next sentence, though the second pass does add the AR page/embeds detail.

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

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

No output schema exists, yet the description covers permanence, the full cascade of deletions, the public-state impact, and the required auth scope. An agent has everything needed to decide and call 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% — both 'id' and 'idempotency_key' are documented in the schema, including the repeat-safe retry semantics. The description adds no parameter-level syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (delete) and resource (item) and immediately qualifies the operation: unpublish-first, then removal of images, models and QR. This distinguishes it from siblings like unpublishItem (which keeps the item) and deleteCatalog (a different resource).

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 prerequisites ('Requires scope: upload_images', 'same scope as creating items') and the permanence warning, which tell an agent when this is appropriate. It does not explicitly name unpublishItem as the non-destructive alternative, so routing between the two must be inferred.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that by naming the required auth scope (create_qr) and by signalling via 'regenerate' that an existing QR is replaced — though it doesn't say whether previously issued/printed codes are invalidated.

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 short sentences with zero filler; the action is front-loaded and the scope requirement follows immediately. Every 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 mutating, non-readOnly tool with no output schema, the description omits how the generated SVG is returned (inline string, URL, or attachment) and says nothing about the idempotency_key parameter it accepts. It covers the operation and its auth requirement but leaves the response contract implicit.

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

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

Schema description coverage is 100%, so both `id` and `idempotency_key` are fully documented in the schema, establishing the baseline of 3. The description adds no parameter-level meaning (e.g., what regeneration does with an existing idempotency key) beyond what the schema already provides.

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

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

States a specific verb ('Generate (or regenerate)') and resource ('the item's QR code SVG'), and the 'regenerate' parenthetical usefully signals overwrite semantics. No sibling tool overlaps this capability, so the agent can distinguish it, though the description never explicitly contrasts with siblings like getItem.

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 prerequisite ('Requires scope: create_qr'), which is actionable context, but offers no when-to-use guidance, no indication of when to call this versus retrieving an existing QR, and no note on whether regeneration is safe to invoke repeatedly.

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 destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: the required auth scope (read_catalog) and the fact that the response carries status and next_allowed_actions, which hints at state-dependent behavior.

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 short sentences with zero filler; the core behavior is front-loaded and the prerequisite follows. Nothing could be cut without losing information.

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

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

For a single-item read tool with full parameter coverage and no output schema, the description covers purpose, scope requirement, and the shape of the return. It lacks pagination/not-found or error behavior, but nothing essential to invoking 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?

Only one parameter exists and the schema documents it at 100% coverage (UUID string), so the baseline is 3. The description implies the id identifies a single item but adds no format or lookup semantics beyond the schema.

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

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

States a specific verb (Get) and resource (one item) and names the payload fields returned (status, next_allowed_actions), which distinguishes it from the many sibling list/get tools. It does not explicitly contrast with getItemLinks or listItems, 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?

The 'Requires scope: read_catalog' line gives a real prerequisite, which is useful context for selecting this tool. However, there is no guidance on when to prefer this over listItems or getItemLinks, and no exclusions, so usage is only 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds two things annotations cannot convey: the required authorization scope ('read_catalog') and the conditional nature of the QR field, which may be absent unless previously generated.

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 short sentences with no filler, and the payload contents are front-loaded before the auth prerequisite. The first sentence is a telegraphic noun list rather than a clause, which is efficient but slightly less readable.

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 return payload (AR URL, embed URL, embed snippets, QR) and states the auth scope, which is what an agent needs to call and interpret this one-parameter read. It stops short of noting behavior when an item has no public URL or QR yet.

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 'id' UUID parameter, so the schema fully documents it. The description adds no syntax, format, or constraint detail about the identifier, so the baseline 3 applies.

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

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

The description names the specific resource returned — public AR URL, embed URL, embed snippets, and QR — which lets an agent distinguish it from generateItemQr (which creates a QR) and getItem (which returns item data). The verb is only implied by the tool name, but the returned artifact set is concrete and 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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The only conditional hint is '(if generated)', which implies QR may not exist but does not tell the agent when this tool is the right choice over getItem or generateItemQr.

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 the non-obvious auth requirement (read_usage scope), which is genuine value beyond the structured fields. It does not describe return shape, but the annotations lower the bar.

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 short sentences, zero waste, with the return content stated first and the scope requirement second. Nothing to trim.

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 burden of saying what comes back, and it does list the three returned concerns (identity, plan, credits). It stops short of detail on field structure, but for a zero-parameter self-lookup this is close to 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?

The tool takes zero parameters, so there is nothing for the description to clarify. Full credit at the 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 names a specific resource set: the caller's identity, plan, and credit balance. An agent can immediately tell this apart from its siblings, which all deal with items, catalogs, or generation workflows. The verb is only implied ('Who am I'), keeping it 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?

'Requires scope: read_usage' gives a concrete prerequisite for calling it. However, there is no guidance on when to prefer this over listCreditLedger or listAgents, so the agent must infer that this is the self-lookup variant.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the read_usage scope requirement, that keys attach to an agent and calls run as the owner, the optional daily credit cap, the audit trail, and that creation/suspension happens outside this tool.

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

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

The purpose is front-loaded in the first sentence, and the following sentences build a coherent mental model of the entity. It is slightly verbose for a no-argument list tool, since the credit-cap and audit-trail details are tangential to invoking it, but nothing is redundant.

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

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

With no parameters and no output schema, the description carries the burden of explaining what comes back, and the agent-identity definition largely does that. It stops short of describing the list's shape or ordering/pagination, which would be the remaining useful detail, but it is sufficient to call the tool correctly.

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

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

The tool takes no parameters (schema coverage 100%, empty object with additionalProperties=false), so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter tool.

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 ('List the account's agent identities') and then defines what an agent is (an identity owned by the account, kind agent or service), which removes ambiguity about the entity being returned. It never explicitly distinguishes itself from siblings such as getMe, but there is no overlapping sibling for agent listing, so the gap is minor.

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 concrete prerequisite ('Requires scope: read_usage') and notes that agents are created and suspended by a human in the dashboard, implying this tool is the read path for them. There is no explicit when-to-use/when-not guidance or named alternative, so usage remains implied rather than spelled out.

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 a genuinely useful behavioral requirement the annotations do not carry: the read_catalog scope needed to call it. It omits pagination or result-size behavior, keeping it below 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?

Two short sentences, purpose first, prerequisite second, with no filler or redundancy. Every 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 parameterless read-only list tool with no output schema, the description covers what it does, the auth scope required, and the read-only nature is confirmed by annotations. Only a note about return shape or result limits is missing.

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

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

The tool takes zero parameters and the schema coverage is effectively 100%, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless tool.

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 account's catalogs'), which is unambiguous against siblings like listItems, listAgents, and listWebhookEndpoints because the resource noun differs. It stops short of explicitly contrasting with those list siblings, but the resource makes the boundary self-evident.

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 hard prerequisite (requires scope: read_catalog) but never states when to use this tool versus alternatives, nor any exclusions. Usage is only implied by the fact that it is the sole catalog-listing tool.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description only needs to add context beyond that. It does: newest-first ordering, cursor-based pagination, the exact ledger entry categories returned, and the read_usage scope requirement — all things annotations cannot express. It stops short of describing entry fields or pagination termination behavior.

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 compact sentences, zero filler, and the core identity (ledger + ordering + pagination) is front-loaded before the query and scope details. Every clause carries information the agent needs.

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

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

With no output schema, the description usefully enumerates what a ledger entry represents (debits and credits of four types), covers ordering, pagination, and auth scope. It is nearly complete for a read-only list tool; only the shape of individual entries and end-of-pagination behavior are left unspecified, which is a minor 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 50% (only cursor is documented in the schema). The description compensates meaningfully by giving the limit range (1–100) and by explaining that cursor is a created_at value taken from next_cursor, which is a semantic detail the schema does not provide. Default page size is left to 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+resource (the account's credit ledger), plus its contents (generation charges, refunds, plan allocations, top-ups), ordering (newest first), and pagination model. No sibling tool reads ledger data, and the description's specificity makes that separation obvious 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?

Usage is implied by the resource ('query the ledger for charges/refunds/allocations') and it names the required scope (read_usage), which is genuinely actionable. However, there is no explicit when-to-use/when-not-to-use statement or routing to an alternative view of the same data, so it stays at the implied-usage level.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description is not carrying the safety burden. It adds genuinely structured context the annotations do not: the required read_usage scope, the exact meaning of credit_cost (what the generate call will debit per provider), and the is_default fallback rule for unpinned items.

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 and cost, then field semantics, then prerequisite scope. The dense parenthetical about credit_cost earns its place because the tool has no output schema to explain the field elsewhere.

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 describe the payload — and it does, listing the fields returned and the is_default rule. Auth scope, cost semantics, and cross-endpoint relationships are all present, leaving nothing an agent needs to call this 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 there is nothing for the description to disambiguate and schema coverage is moot. The description instead spends its space documenting the response shape, which is appropriate, though field-level semantics are partial (release_stage and format values are not 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?

First sentence states the specific resource (generation options for this account) and the key attribute (credit cost), which clearly separates it from listCreditLedger, getMe, and startGeneration. It also enumerates what each option carries (credit_cost, release_stage, image limits, output formats, is_default), so an agent knows what it gets without opening anything else.

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?

"Read before spending" gives an explicit trigger tied to the paid generation path (POST /v1/items/{id}/generate), and the note that GET /v1/items/{id} returns generation.estimated_credit_cost tells the agent when per-item costing should come from getItem instead. Both the when and the alternative are named rather than inferred.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavioral context beyond them: newest-first ordering, cursor pagination semantics, the limit range/default, and the required read_catalog scope.

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 dense sentence that front-loads what the tool returns and its ordering, then packs parameters and the scope requirement without filler. Every clause carries information.

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

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

With no output schema, the description covers the return ordering and pagination contract (next_cursor) that an agent needs. The only gap is that the accepted values for status are never enumerated, leaving the filter open-ended.

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 67%, with limit documented only via minimum/maximum/default keywords. The description compensates by restating the 1–100 range and default 25 and by clarifying that cursor is a created_at ISO string taken from next_cursor, adding format meaning the schema only partially 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 the account's items') plus scope ('the account's'), ordering ('newest first') and pagination model ('cursor-paginated'). An agent can distinguish it from getItem (single) and listCatalogs (different resource), though no sibling is named 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?

Usage is implied by the listing semantics and the stated prerequisite ('Requires scope: read_catalog'), but there is no explicit when-to-use guidance, no mention of when to prefer getItem or listCatalogs, and no exclusion conditions.

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, yet the description adds substantial context beyond them: the exact signature scheme (Pixeloa-Signature with HMAC-SHA256 construction), retry backoff up to 12h, auto-disable after 20 consecutive failures, and the read_usage scope requirement. This is genuinely useful operational context an agent wouldn't get from the structured fields.

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 purpose, then supporting detail. The HMAC signature breakdown is somewhat tangential to invoking a list call and lengthens the definition, but it is dense and each sentence carries information rather than 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?

No output schema exists, so ideally the description would sketch the returned shape (endpoint fields), and it only says 'endpoints and the event types.' Still, for a zero-parameter, read-only list tool with annotations covering the safety profile, this is largely complete; only the return structure is left implicit.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. The description correctly implies a no-argument call scoped to the account.

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: 'List the account's webhook endpoints and the event types.' No sibling tool covers webhooks (siblings are item/catalog/agent tools), so the agent can route here without ambiguity. It also clarifies the human-created nature of endpoints, sharpening what the resource is.

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 usage context: endpoints are created in the dashboard, and a key 'can list them but never add or redirect one,' which bounds what this call can do. It also states the required scope (read_usage). It stops short of naming an alternative tool or a when-not-to-call condition, but none is needed given there are no sibling webhook 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?

Goes well beyond the annotations by disclosing the plan-limit failure (403 plan_limit_reached), the eligibility conflict shape (409 with details.state/details.blockers), the slug-minting side effect on first publish, the returned public.ar_url and public.embed_url, and the required scope: publish_items. The idempotency_key note is consistent with idempotentHint=false (not inherently idempotent, but a key makes retries safe).

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 dense with genuinely useful information; every clause carries an error code, precondition, or return field. The single dense block is a bit run-on but wastes little.

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 still conveys the salient return fields (public.ar_url, public.embed_url), all known error paths, the auth scope, and the precondition check. 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 description coverage is 100%, so both parameters (id and idempotency_key) are already documented in the schema. The description adds no parameter-level syntax or format detail beyond what the schema provides, making the 3 baseline correct.

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 ('Publish the item's public AR page') and immediately clarifies the state transition ('Makes the item public'). An agent can distinguish it from unpublishItem 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 a clear precondition ('Check item.publishable before calling') and explains the API-created-item default ('items created via the API start private'). It does not explicitly name unpublishItem as the inverse operation, so routing guidance is strong but not exhaustive.

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=true and idempotentHint=true, so the safety profile is covered. The description adds the required authorization scope, which annotations do not convey and which an agent needs before attempting the call. It stops short of saying whether the removal is reversible or how failures are reported.

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 short sentences, action first, prerequisite second, with no redundant restatement of the title or 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?

With rich annotations and no output schema, the definition covers the essential operation and its auth requirement. It would be complete if it clarified catalog-scoping versus deleteItem, but nothing critical to calling 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 description coverage is 100% and the idempotency_key field already documents repeat-safe retry semantics in the schema. The description adds nothing about which id is the catalog and which is the item, so the baseline of 3 applies.

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

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

States a specific verb (Remove) and resource (item from a catalog), which clearly separates it from siblings like addCatalogItem and listItems. It does not, however, explicitly distinguish itself from deleteItem, which an agent could easily confuse with catalog-scoped removal.

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 supplies one prerequisite (scope: write_catalog), which is genuinely useful for invocation. It gives no guidance on when to prefer this over deleteItem or deleteCatalog, nor any note that removal is catalog-scoped rather than global.

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 safety flags (readOnlyHint=false, destructiveHint=false), so the description carries the real behavioral load: it spends credits, is asynchronous with a specific polling endpoint and success condition (model.available), returns 402 and 409 in named failure modes, and requires the start_generation scope. That is far beyond what the structured fields 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?

Front-loaded with purpose and cost, then prerequisites, then async/error behavior, then the scope. Dense and largely earned, though the parenthetical asides and the all-caps credit warning make it slightly heavy for two sentences of core content.

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

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

For an async mutation with no output schema, the description supplies everything an agent needs: state eligibility, async delivery mechanism and terminal condition, error codes, cost/auth requirements, and retry semantics. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents both id and idempotency_key, and the description adds little on their syntax. It does add useful state context around which id values are eligible (confirmed vs. failed vs. ready), which is the baseline-plus level rather than a genuine augmentation of parameter 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?

The description opens with a specific verb+resource ('Start 3D generation') and immediately flags the cost, which distinguishes it from sibling generators like listGenerationOptions, createItem, and confirmScale. An agent can tell what it does and what it costs 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 gives explicit preconditions ('Requires status confirmed with confirmed dimensions'), explicit exclusions ('A ready item is never regenerated in place'), an allowed retry case ('a failed generation may be attempted again'), and names the alternative action (create a new item from the images). This is exactly the when/when-not/alternative structure.

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=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: the required 'publish_items' scope, an explicit 'CHANGES PUBLIC STATE' warning, and the downstream effect that all embeds go quiet.

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 short sentences with zero filler, and the highest-value information (what it does, that it mutates public state) is front-loaded.

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 and annotations covering the safety profile, the description supplies the missing pieces: scope requirement and the effect on public visibility. It could note retry/repeat behavior, but the schema's idempotency_key description already covers that.

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

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

Schema description coverage is 100%, so the schema fully documents both 'id' and 'idempotency_key'. The description adds nothing about parameter meaning or format, which is the correct baseline when the schema does the work.

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 ('Unpublish') and resource ('the item's public AR page'), plus the concrete effect on embeds. It is immediately distinguishable from the sibling publishItem 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?

Usage is only implied: an agent infers you call this to take a public page offline. No alternative tool is named, and no conditions or exclusions are given, so it sits at the minimum-viable level.

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 (readOnly=false, idempotent=false, destructive=false), the description discloses the 422 validation_error path for non-public or off-site URLs, the null-clearing semantics (label clears with it), the 60-char cap, the analytics side effect, and the required publish_items scope. This is unusually rich for a mutation tool and gives the agent the failure and side-effect 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 in the first clause, followed by constraints in priority order (URL rules, clearing, label, analytics, scope). Every sentence contributes actionable information with no restatement of the tool name or 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 4-param mutation tool with no output schema, the description covers validation, clearing behavior, side effects and authorization scope. It does not mention what happens to other item settings or the response shape, but the safety annotations plus this content leave little an agent needs 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 coverage is only 50%, and the description compensates for exactly the undocumented parameters: product_url gets URL constraints (public https, own site, not pixeloa.ai/private network, nullable to clear) and product_cta_label gets its 60-char limit and override behavior. It adds real meaning the 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 ('Update the item's public-page settings') and narrows scope to the 'product CTA link', so an agent can distinguish it from mutation siblings like publishItem or unpublishItem. It stops short of naming those siblings explicitly, which is the only thing keeping 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?

Usage context is implied rather than stated: it explains that the tool sets the 'view product' button on the public AR page and embeds, which tells the agent when the tool is relevant. It never names an alternative tool or an explicit when-not condition, so routing guidance 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.