Cellionaire

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

Adds real context beyond the annotations: it confirms no reservation or charge occurs despite wrapping POST /api/quote, and it enumerates the three eligibility gates that can block an order. The one unexplained trait is idempotentHint=false – the definition only hints ("right now") that prices/quotes may change between calls rather than saying so.

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: what it does and returns, then the no-side-effect guarantee, then coordinate conventions. Front-loaded purpose with zero filler, and the coordinate note is placed where an agent needs it before building areas.

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 carries the return burden by naming both outputs – prices and an orderable verdict with reasons. It does not say how those results are shaped across multiple areas (per-area breakdown vs aggregate), which is the remaining gap for a batch-quote 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?

Schema coverage is 100% and the schema itself documents rect/cells/color, so the baseline is 3. The description earns above baseline by supplying orientation semantics the schema lacks: x left-to-right, y top-to-bottom over 0..999, and the cell index formula y*1000 + x.

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 ("Price a selection of cells") and the exact decision returned (orderable: meets minimum, not reserved, not in image review). It is clearly separable from siblings create_order and get_order_status because it prices and evaluates without committing anything.

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?

"right now" plus "Nothing is reserved or charged" establishes this as the pre-flight quote step before create_order, giving clear usage context. It stops short of an explicit "use create_order instead when you want to actually buy" routing sentence.

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 this as a non-readonly, non-idempotent, closed-world mutation; the description adds substantial context beyond that: no payment is performed, the caller must transfer USDC before pay_by, and rate/per-IP limits apply. It does not explicitly warn that repeated calls create additional unpaid orders (relevant given idempotentHint=false), which is the one behavioral 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?

Front-loaded with the action and the return payload, then moves through the payment caveat, limits, terms, and coordinates in a logical order. Dense but nearly every clause carries operational information; the parenthetical field list is slightly heavy but useful given there is no output schema.

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

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

For a mutating, non-idempotent creation tool with no output schema, the description compensates well by enumerating the returned payment fields and spelling out limits and coordinate rules. The only shortfall is the network enum ('solana' vs 'base') being described only as 'the USDC network you will pay on', while the return payload mentions a Solana reference specifically.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: coordinate orientation (x left-to-right, y top-to-bottom, both 0..999), the cell index formula y*1000+x, and the semantic of accepted_terms as acceptance of the linked terms. It does not explain the solana vs base network choice or the 'base' payment reference.

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

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

States a specific verb and resource ('Create an order for cells') and immediately scopes the outcome ('return the USDC payment details'), listing the exact returned fields. This clearly separates it from siblings like get_order_status and check_cells_available, which do not create anything.

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 tells the caller what this tool does NOT do ('This tool does not pay: the caller sends the USDC transfer itself before pay_by'), which is the critical usage decision for this workflow. It also states constraints (minimum cells, max 16 colours, no image orders, rate limits, unpaid orders per IP) and the terms requirement, though it never names a sibling as an alternative for related operations.

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. Beyond that, the description adds real value by disclosing the returned payment fields and enumerating the ten possible status values, which tells the agent what a response can look like. It stops short of describing error behavior, such as what happens for an unknown or expired order id.

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

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

Two sentences, front-loaded with the resource and the data it returns, followed by the endpoint and the status vocabulary. The long status list is dense but each token is a meaningful return value. No filler or redundant restatement of the tool name.

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 describing return values, and it does list the relevant fields and status values. However, it omits how to source the order_id and what an error or unknown-order response looks like, both of which matter for a polling-style lookup 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?

Schema description coverage is 0% and the single parameter order_id has only a regex pattern, no prose. The description contributes nothing beyond '{id}' — it never says the id is a 16-character hex string or, more importantly, where the agent obtains one (presumably from create_order). For a one-parameter tool with zero schema documentation, the description should compensate and does not.

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 (an order and its USDC payment) and enumerates the fields it reports: state, received, remaining, confirmations, refunds. It also identifies the underlying endpoint (GET /api/order/{id}), which pins down the operation precisely. It does not explicitly contrast itself with siblings like create_order, but the siblings are distinct enough that confusion is unlikely.

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 can infer this is the read-side counterpart to create_order, used to poll or inspect an order's payment progress. There is no explicit statement of when to use it, when not to, or prerequisites such as needing a previously created order. The status enum hints at polling scenarios but never says so.

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, closed-world, and non-destructive, so the safety profile is fully covered. The description adds useful behavioral context beyond that: the numbers are pulled from live settings rather than a cache, and it removes input ambiguity with 'No input.' Return shape is described by field enumeration, though no pagination or error behavior is mentioned.

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?

Very short and front-loaded: the returned fields are listed first, followed by the freshness note and the input statement. The comma-separated enumeration is dense but readable, and no sentence is wasted, though 'No input' lightly duplicates the empty 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 no output schema, the description carries the burden of conveying return values, and it does so by enumerating each field including the boolean purchase status. Combined with full annotation coverage and an empty input schema, an agent has enough to call it correctly; only the relationship to sibling overview tools is unaddressed.

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

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

The tool takes zero parameters, so the baseline is 4. The description's 'No input' explicitly confirms the parameterless contract, leaving nothing for the schema to clarify further.

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

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

States a clear resource (wall settings) and enumerates the exact contents returned: rules, prices, size, minimum order, payment networks, terms version, and open/closed purchase status. An agent knows precisely what data it gets. It does not differentiate from the sibling wall_overview or read_region, so it falls 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?

There is no explicit when-to-use guidance, no mention of prerequisites, and no routing away from the overlapping siblings wall_overview or read_region. The only implicit cue is that the values are needed for ordering decisions, which the agent must infer.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds the hard constraint w*h <= 10000 and the underlying GET /api/region call, which are real behavioral facts not present in structured fields. Undisclosed: what happens when the rectangle exceeds the pixel cap (error vs clamp) and any rate limiting on the wrapped endpoint.

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 size cap, then format semantics, then the coordinate system — no filler sentences and nothing repeated from annotations. The coordinate clause is densely packed into one line, which slightly hurts parseability but not 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?

With no output schema, the description still explains the payload for both formats (base64 RGBA + empty/buyer/house runs with public display names; PNG image), which is what an agent needs to consume results. It leaves error/edge behavior unstated, notably rectangle-size violation handling and whether partial off-wall regions are clipped.

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: x is left-to-right 0..999, y is top-to-bottom 0..999, w/h must satisfy the w*h <= 10000 product bound, and format's two enum values are explained with the default. It even gives the cell-index formula y*1000 + x, meaning not expressible in the JSON schema at all.

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 ('Pixels and owners of a rectangle'), names the two output formats, and pins the exact HTTP endpoint it wraps. An agent can distinguish this from wall_overview (whole-wall aggregate) and check_cells_available (availability probe) without opening a sibling 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?

Explains the choice between the two formats with their contents — json yields base64 RGBA plus owner runs, png yields an image — and states json is the default, which is directly actionable. It stops short of routing the agent against siblings (e.g. use wall_overview for a coarse view, check_cells_available before buying) or stating when not to call it.

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 behavior the annotations cannot: the exact pixel-to-cell mapping and the alpha conventions (0 empty, 255 bought, 254 site-owned art), which materially change how the returned PNG must be interpreted. It stops short of naming the endpoint host or pagination/versioning behavior, so not a 5.

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

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

Two short sentences plus an endpoint note, front-loaded with the highest-value information (version and PNG URL) and the encoding legend. The middle clause 'and how to read regions' is dangling and never resolved, which is the only real waste. No redundant restatement of the tool name.

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 carry return-value meaning, and it does convey the key fields and pixel legend. However, 'how to read regions' is promised but not actually explained, and there is no statement of the version format or whether the PNG URL expires. For a zero-parameter informational tool this is workable but leaves a 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify. 'No input' correctly reaffirms the empty schema and prevents an agent from inventing required arguments.

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 enumerates return contents (wall version, full-wall PNG URL, pixel encoding) rather than stating a verb+resource, so the purpose is inferred rather than declared. It does not differentiate itself from the very similar sibling get_wall_info, leaving an agent unsure which of the two to call. The pixel-encoding detail is distinctive, which keeps it above tautology.

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 when-to-use guidance and no mention of the alternatives (get_wall_info, read_region, check_cells_available) despite clear overlap with at least two siblings. The phrase 'how to read regions' faintly implies this is a prerequisite for interpreting region reads, but that inference is never made explicit. The agent must guess the selection rule.

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