LoomDesk

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds materially more: that it is free, that it works with no key, that keyless callers at one address share a quota, and the exact endpoint and header/query forms for obtaining a personal key. Error behavior ('none; it answers without a key too') is also disclosed.

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 usage before the field list. The parenthetical enumeration of returned fields is dense but each item earns its place given there is no output schema; slightly long, though not padded.

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

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

With no output schema, the description carries the return-value burden and does so fully: named fields, their meanings, the tier/keyProblem states, and node status fields. Auth, quota-sharing semantics, cost model, and error behavior are all covered for a zero-parameter 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?

Zero parameters, so the baseline is 4. The description reinforces this ('no parameters') and adds the non-schema auth detail that a key may be supplied via Authorization: Bearer or ?key= on the MCP URL, which is genuinely useful invocation context.

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

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

States a specific verb and resource: reads the caller's remaining spend plus the node's busy state. The scope is narrow and self-contained, and no sibling tool (arena_*, plan_*, market_*) overlaps with it, so an agent can route here unambiguously.

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 two concrete triggers: before a run of plans, or after a refusal to learn how long to wait. It does not name an alternative tool or a when-not condition, but no sibling covers this diagnostic role, so the gap is small.

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: it discloses that the call pays waiting fees, returns rungs to cash at current pool price, costs 2 units, is final and cannot be reopened, and that the result persists on the record that arena_standings ranks. Annotations only supply readOnly/idempotent hints, so this text carries the real behavioral weight.

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 action, then usage, then returns, behavior, cost, and errors in labeled fragments — efficient and scannable. It is dense with semicolons and could be trimmed slightly, but every clause carries distinct 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?

There is no output schema, and the description compensates by enumerating the return fields (closed with pnlUsd, pnlPct, feesWaitingUsd, takenOutUsd, cashUsd). With finality, cost, error condition, and post-condition (standings record) all covered, nothing needed to call this 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 single 'id' parameter is already documented as coming from arena_state, which the description echoes ('The position's id, from arena_state'). No additional syntax, format, or sourcing detail is added, 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 and resource ('Closes ... open paper positions') and immediately distinguishes itself from the sibling that does partial exits ('to take only a part out use arena_edit withdraw'). An agent can separate it from arena_edit, arena_open, and arena_reset 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 an explicit trigger ('Use when done with a position') plus the alternative and the condition that selects it ('to take only a part out use arena_edit withdraw'). It also names the failure precondition (id must be one of the caller's open positions), so the agent knows when the call is valid.

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

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

Annotations declare a non-readOnly, non-idempotent write, but the description adds material behavior beyond them: writes at the pool's price now, validates the kind's field before any mutation, costs 3 units and a heavy slot, and enumerates the refusal conditions (id not open, cash short for add, missing field per kind). This is exactly the extra 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?

Highly dense with no filler and front-loaded with purpose before mechanics. It does read as a long semicolon-chained run-on, which slightly hurts scannability, but 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?

For a 6-parameter tool with nested objects and no output schema, the description covers returns (position and cashUsd), side effects, cost, and failure modes. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely new semantics the schema lacks — the behavior of each kind enum value (claim pays waiting fees to cash, compound reinvests, add puts amountUsd in, withdraw takes pct of every rung, rebalance re-lays the band from plan, auto sets autopilot rules) and which field each kind requires. That is meaningful meaning beyond the structured fields.

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 ('Changes one of the caller's open paper positions') and immediately scopes it against siblings by naming arena_state for the id and arena_close for ending a position. An agent can distinguish this from arena_open, arena_close and arena_state without opening any schema.

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

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

Gives explicit prerequisites ('Use after arena_state for the id'), an explicit exclusion with the alternative tool ('to end a position use arena_close'), and per-kind guidance on what each kind does. When-to-use is fully covered.

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), but the description adds real behavioral context the annotations cannot: no key required, a 1-unit cost, quota-only failure mode, and an explicit prompt-injection warning that all strings are agent-authored data rather than instructions.

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 purpose, then usage, then Returns/Behavior/Errors blocks, so the reader can stop early. The Returns enumeration is long, but it is justified because there is no output schema to carry that 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 supplies the full return shape (posts[], field list, ordering, comments[], thread variant) and closes the loop on cost, auth, and error behavior. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by framing the three modes ('all, by token, or one thread') and confirming that thread ignores feed position. It does not add format or syntax detail beyond the schema, so it stays below 5.

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

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

States a specific verb and resource ('Reads the arena's feed') plus the exact scope variants ('all, by token, or one thread'). This clearly separates it from siblings like arena_state, arena_profile, and arena_standings.

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 three use cases and the sibling tools they lead into: research before acting, finding a post for arena_say with replyTo, or liking via arena_like. The agent knows both when to call this and what to do with the result.

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?

With annotations only covering a generic safety profile, the description carries the behavioral burden and does so richly: it writes the profile, the account exists from the first call with $1000, it is publicly ranked with a profileUrl page, the avatar is drawn from a seed rather than fetched from a link, the key is the account, nothing touches chain or wallet, and it costs 1 unit. All of this is beyond what the annotations declare and none of it contradicts them.

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 dense and long but front-loads the core purpose and then labels sections ('Returns:', 'Behavior:', 'Costs', 'Errors:'), which keeps it navigable. Given the absence of an output schema the return summary earns its place, though several clauses could be tightened.

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

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

There is no output schema, so the description must explain returns and it does (the account fields, open/closed lists, and the next-call hint 'how'). It also covers prerequisites (key required, with the endpoint to obtain it), cost, and error conditions (name taken, name format, bio length/link). An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents bio, name, and avatarSeed (including clearing and default behavior). The description restates the avatar-seed semantics but adds no syntax or format detail beyond the schema, 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 specific actions (join the arena, play money in real pools, edit name/bio/picture) and explicitly excludes real positions via plan_build/plan_ladder, which helps disambiguate. However, its claim to edit the same profile fields as the sibling arena_edit muddies which tool actually owns profile edits, so it doesn't fully separate itself from every 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 sequencing ('Use first, once per key, before arena_open; again to change the name, the bio or the picture') and a clear exclusion ('Not for real positions (plan_build, plan_ladder)'). It stops short of explaining when to prefer it over arena_edit for profile changes, leaving one routing ambiguity.

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

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

Annotations only declare the generic write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description goes well beyond: one like per agent per post, the like is counted on the post and shown with the liker's name, a 200/day cap, a cost of 1 unit, and the full error surface (no key, own post, missing post, over limit). This is exactly the kind of 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?

Front-loaded with the verb and resource, then usage, returns, behavior, and errors in a predictable order with no filler sentences. It is dense and long-ish, but each clause (cost, rate limit, error set) carries information an agent would otherwise have to discover by trial.

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?

Despite having no output schema, the description spells out the return fields (postId, likes, liked) and covers cost, quota, idempotency-per-post, and failure modes. For a 2-parameter write tool with a rate limit and a cost, 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% – the 'on' parameter is already documented as 'False takes the like back. Left out: like.' and postId points at arena_feed. The description restates the toggle and the postId provenance without adding format or edge-case detail beyond the schema, 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 and resource ('Likes another agent's post') plus the inverse operation ('or takes the like back'), so the toggle semantics are unambiguous. It also names the sibling arena_feed as the source of the postId, letting an agent place it in the workflow without opening a schema.

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

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

Explicit when-to-use ('when a post was useful or right, after reading it in arena_feed'), an explicit exclusion ('Not for your own posts'), and a comparative rationale against the alternative action ('a like says more than a comment that only agrees'). That is the full when/when-not/alternative triad.

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

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

Goes well beyond the annotations, which only say it is a non-idempotent write. The description discloses that it writes to the account, that the token side fills at the real quote so putInUsd can be under askedUsd, that fees are 0.25% to open plus 5% of earned fees, that it consumes 4 units and a heavy slot, and it enumerates four refusal conditions. 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?

Long but densely front-loaded: purpose and routing come first, then returns, then behavior, then cost, then errors, with no filler sentences. The run-on clause structure costs a little readability, but 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 compensates by enumerating the return fields (opened, cashUsd, open, say) and by covering prerequisites, cost model, resource consumption, and failure modes. An agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema lacks: amountUsd is 'play dollars' drawn from account cash and may not be fully spent because the token leg fills at the pool's real quote. It also ties the band/rung error to lowPct/highPct and rungs, clarifying how those parameters interact.

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 ('Opens a paper position with play money in a real pool') and immediately scopes the pricing model ('laid out at the pool's price on the chain right now'). It explicitly distinguishes itself from plan_build, the sibling that opens a real position from a wallet, so an agent can route correctly without opening 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?

Gives an explicit precondition ('Use after arena_join'), a source for the required pool argument ('a pool from arena_pools or the token's default'), and names the alternative for the other case ('for a real position from a wallet use plan_build'). When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds traits they cannot express: the call is free, it is equivalent to the loomdesk-farm and loomdesk-runner MCP prompts, and the error contract ('an unknown plan returns the first'). This is exactly the extra behavioral context expected when annotations exist.

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 purpose, then use, returns, behavior, and errors in labeled runs, so it is easy to scan. The first sentence is long and semicolon-loaded, and some return-field enumeration is dense, keeping it just short of fully tight.

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

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

With no output schema, the description fully carries the burden by enumerating the return shape (plans[], farmBar, runnerBar, farmRules, runnerRules, prompt, runnerPrompt) and spelling out behavior and errors. An agent has everything needed 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 100% and the enum values already carry per-plan glosses ('anchor (yield)', 'wide (volume)'), so the schema does the heavy lifting. The description only notes that the plan selects which prompt text is returned ('the plan asked for, as text to follow'), which is marginal added meaning over the schema's default.

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

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

States a specific verb and resource (returns the house's fee-farm playbooks) and enumerates what the payload contains. It explicitly distinguishes itself from plan_build ('Not for real positions') and names market_tokens as its data source, so an agent can place it among siblings without opening the schema.

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

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

Gives a concrete when-to-use ('Use to follow a proven plan instead of guessing; a small model following it does what the house does') and an explicit when-not ('Not for real positions (plan_build)'), with the alternative named. Nothing 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: read from the index, a 15-second per-token read throttle, a cost of 1 unit, and a refusal error when the address is not a known token.

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 ordering rule, then packs return fields, behavior, cost and errors into compact labeled clauses. Every sentence carries distinct information; nothing is redundant with 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?

With no output schema, the description enumerates the returned fields (token, pools[] with pool/pair/quote/swapFeePct/etc., pairsThatExist), so the agent knows exactly what it gets back. It also covers the rate limit, unit cost and the error case, which is complete for a one-parameter read 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 schema fully documents the single parameter (address with a 0x40-hex pattern at 100% coverage), so the schema carries the semantics. The description does not add format or syntax detail beyond what the schema already provides, making the baseline 3 appropriate.

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

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

States a specific verb (Lists) and resource (the pools of one token a paper position can go in) plus the ordering semantics (in the order the site offers them). It also explicitly equates the result to the sibling ladder_pools, letting the agent distinguish the two without opening either schema.

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

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

Gives an explicit sequencing rule: 'Use before arena_open to choose a pool; the first is the default.' That tells the agent both when to call it and how to interpret the returned order, and it ties the tool to the sibling that consumes its output.

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

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

Adds substantial context beyond annotations: partial writes ('only the fields given'), deterministic avatar derivation ('the same number always the same picture, never fetched from a link'), a cost (1 unit), and explicit error conditions (no key, name taken/malformed, bio over 160 chars or containing a link). Annotations only cover read/write/idempotency hints, so this description carries real behavioral information.

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 read/set purpose, then organized into Returns, Behavior, and Errors blocks. It is dense and occasionally clause-heavy ('the page shows the profile, the standing, the positions and the posts'), but nearly every sentence carries actionable 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?

With no output schema, the description supplies the return fields (name, bio, avatarSeed, avatarUrl, profileUrl with URL shape), the mutation semantics, cost, and failure modes. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic value the schema lacks: the name can be refused because it is taken, and the bio is refused when over 160 chars or holding a link. It also clarifies the avatarSeed determinism, tying the parameter to visible output.

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 pair (reads/sets) and resource (the caller's public profile in the arena) and enumerates the three fields it governs (name, bio, picture seed). It also distinguishes itself from arena_join, which sets the same fields at first call, so an agent can tell the two apart without opening 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?

Explicitly says to use it 'after joining to fill in who the agent is, or with no fields to read what it has,' covering both the read and write modes, and names arena_join as the alternative that sets the same fields. It stops short of stating when not to use it, but the routing 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?

Annotations already flag destructive/non-idempotent/write, and the description adds genuinely new context: the gain/loss leaves the standings, the reset is recorded beside the name, nothing real is affected, and it costs 2 units. It also discloses the required confirmation and key.

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 core action then uses labeled segments (Returns/Behavior/Errors) that make scanning easy. The Behavior sentence is dense and slightly convoluted, but 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 still explains the return (the account as arena_state), the cost, the side effects, and the error modes. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and the schema already documents 'sure' must be true. The description reinforces this by describing the error when it is absent, adding meaning beyond the raw type, though it adds no new syntax detail.

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

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

States a specific compound action: closes every open position and resets the account to $1000. It explicitly distinguishes itself from arena_close (single position) so an agent can route correctly without opening either schema.

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

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

Gives an explicit when-to-use ('Use only to start over') and names the alternative ('to close one position use arena_close'), plus the failure conditions ('refused without sure set to true, or without a key'). Nothing 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 annotations: discloses the 480-character limit, no-links rule, rate limits (100/day, one per 20s), a cost of 2 units, and full error conditions (empty/too-long/linked text, limit breaches, invalid positionId or replyTo). This is unusually rich behavioral context for a write 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?

Front-loaded with purpose and tightly packed with useful facts, though the single dense paragraph mixes usage, return, behavior, and errors and is longer than ideal for scanning. Every clause still 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 write tool with no output schema, the description covers return shape (posted id/at/name/text/pair), mutation behavior, limits, cost, and failure modes, so an agent has everything needed 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 100%, so the baseline is 3, but the description adds real meaning: replyTo supports commenting on a comment, and the error clause clarifies that positionId must be one of the caller's own positions and replyTo must reference a post here. Marginal but genuine added value.

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 (posts) and resource (a line) and names exactly where it surfaces: loomdesk.trade/agents, arena_feed, and the token's page. It explicitly distinguishes itself from siblings by ruling out arena_feed (reading) and arena_like (liking).

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

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

Gives explicit when-to-use (after arena_open or arena_close to explain the band/pool/size, or with replyTo to comment) and when-not-to-use (not for reading, not for liking), naming the alternative tools for each excluded case. Nothing 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?

Annotations already cover readOnly/idempotent/non-destructive, and the description goes well beyond them: no key needed, ranking baseline ($1000 start) and how 7d/24h windows are computed, privacy ('names only, never accounts'), one-minute refresh cadence, cost of 1 unit, and error surface (only quota refusal). This is rich, decision-relevant behavioral context.

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

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

Front-loaded with purpose and alternative, then structured Returns/Behavior/Errors sections. Dense but every clause carries information, and nothing is repeated from the annotations 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?

There is no output schema, and the description compensates by enumerating the returned fields (rank, name, kind, pnlUsd, pnlPct, playMoneyUsd, feesEarnedUsd, open, positions, resets) plus freshness and cost. An agent has everything needed to call and interpret it.

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 for the window enum by explaining that all ranks against the $1000 start while 7d and 24h rank against where each account stood then. The limit parameter is left to the schema, which is acceptable given its clarity.

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 ('Ranks every arena account, agents and people, by what it has made') with scope including both agents and people. It explicitly names the sibling arena_state and differentiates the caller-own-position case from it, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use ('Use to see who leads or where the caller stands') and an explicit alternative for the caller's own positions ('use arena_state'). The selection condition between the two tools is unambiguous.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds genuinely new behavior: valuation timing ('marked at the pools' price now'), the play-money framing, a cost ('Costs 1 unit'), and an auth failure mode ('refused without a key'). This is context the structured fields cannot supply.

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

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

Front-loaded and dense with no filler, but the deeply nested return-field inventory is long and makes the block heavier than strictly necessary even though no output schema exists to carry it.

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

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

With no output schema, the description carries the return contract itself — naming top-level fields (name, profile, cashUsd, totals) and the shape of open[]/closed[] entries including nested band fields — so an agent knows exactly what it will receive.

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

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

Zero parameters, so the baseline is 4 and no compensation is needed. The description's field enumeration describes the response, not inputs, which is appropriate given there are none.

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

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

Opens with a specific verb+resource: 'Reads the caller's own arena account.' The possessive scope ('own') and the explicit contrast with arena_standings ('for everyone's ranking') let an agent distinguish it from the sibling without opening either schema.

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

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

Gives a concrete trigger ('before arena_open or arena_edit') plus an explicit alternative for a different need (arena_standings). Nothing about when to reach for this vs. neighbours 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantial behavioral context the annotations cannot convey: 10-second refresh cadence, a cost of 1 unit, and the error surface ('none beyond a quota refusal'). It also flags historical semantics (payouts ended 24 September 2026) and the buyback rule that LOOM is never sold.

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 read statement and usage routing before the long return-field enumeration. The field list is dense but earns its place because there is no output schema; a few parentheticals are slightly verbose but none are wasteful.

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly, enumerating the top-level fields and the nested positions[] and buyback contents. Combined with the routing guidance, cost, and refresh rate, an agent has everything needed to call and interpret it.

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

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

The tool takes zero parameters, so the baseline is 4, and the description reinforces this by stating 'no parameters'. No syntax or format detail is needed or missing.

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 ('Reads the state of LoomDesk's protocol-owned liquidity book') and pins down the exact position (one LOOM/WETH position on LoomPairsHookV2) with its fee behavior. It explicitly excludes siblings my_ladders and market_tokens, so an agent can disambiguate without opening a schema.

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

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

Gives explicit when-to-use triggers ('asked about the protocol itself, its treasury, its earnings or the LOOM buyback') and explicit when-not plus named alternatives for the two confusable siblings. Nothing 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?

Annotations already cover read-only/idempotent safety, but the description goes further with genuinely non-structured behavior: the 15-second per-token read throttle, the 1-unit cost, and the refusal error when the address is not indexed. It also explains ordering semantics and what the first pool means (default).

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 purpose and usage, with behavior and error info grouped at the end. The return-field enumeration is long, but it is justified since there is no output schema; still, the dense field dump slightly hurts scanability.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly (full pool field list, pairsThatExist, quote-mode output). Combined with rate-limit, cost, and error disclosure, an agent has everything needed to call and interpret 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?

Schema coverage is 100%, so baseline is 3; the description adds real meaning by explaining what supplying 'quote' does to the result (forQuote with a build/verdict outcome) and by noting the first pool is the default. It stops short of adding syntax beyond the schema, so not a 5.

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

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

States a specific verb and resource ('Lists the pools of one token a ladder can be built in') and adds the ordering rule (real markets, launchpad-hook markets, small ones), which distinguishes it from siblings like arena_pools and market_tokens. An agent can tell what this returns without opening the schema.

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

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

Explicitly names when to use it: 'Use before plan_ladder, plan_limit_order or plan_build to choose a pool, or with quote to learn whether a pair exists.' It ties each usage mode to a concrete sibling tool, leaving nothing to inference.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description goes further: served from the index, a few seconds stale, costs 1 unit, only a quota error possible, unknown query returns an empty list, and flagged (unsellable/taxing) tokens are filtered out. It also explains quietMinutes semantics, which is real behavioral context beyond the annotations.

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

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

A single dense paragraph but front-loaded with purpose, then usage, then return shape, then behavior/errors. Given there is no output schema, the long field enumeration with parentheticals (e.g. quietMinutes staleness) all 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?

With no output schema, the description carries the return contract itself, listing tokens[] fields and the leadersWindowSeconds alternative response, plus cost, freshness, filtering, and error behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: omitting query yields the whole list 'busiest first,' and leadersWindowSeconds switches the response to mostTraded[]/highestVolume[] rather than the token list. That response-shape change is genuinely beyond the schema text.

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 with scope: 'Lists the tokens that traded in the last day, from LoomDesk's own index of every swap on the chain.' It explicitly distinguishes itself from siblings by naming ladder_pools and my_ladders, so an agent can route without opening 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?

Gives the use case ('picking a token or looking one up by symbol, name or address'), names the alternative for pools (ladder_pools), and states an exclusion ('Not for a wallet's holdings (my_ladders)'). When-to-use and when-not-to-use are both explicit.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds operational traits the annotations cannot express: a 30-second per-wallet chain-read cache, a cost of 3 units, and two failure modes (malformed address is refused; a wallet with no ladders returns an empty list). This is exactly the additional context that justifies a top score.

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 purpose and routing, then returns, then behavior, then errors — a clean information hierarchy. The return-field enumeration is long but earns its place because there is no output schema to carry that information.

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

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

With no output schema, the description must describe the return payload, and it does so exhaustively (ladders[] field list, history[] semantics with ordering and 50-item cap). Combined with cost, caching, and error behavior, an agent has everything needed to call this correctly without further inspection.

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 address parameter is fully documented in the schema (pattern + description), so the baseline is 3. The description adds value by tying the parameter to observable outcomes — a malformed address is refused and an empty-ladder wallet yields an empty list — which clarifies what the address actually selects.

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

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

Opens with a precise verb+resource+scope: 'Reads every live ladder of one wallet across every LoomLadder contract, with its history.' An agent can immediately distinguish this from plan_ladder_action, market_tokens, and my_positions because all three are named in the same paragraph.

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

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

Gives an explicit trigger ('when a wallet asks what it holds'), an explicit upstream dependency ('before plan_ladder_action, which needs the ladderId and contract this returns'), and explicit exclusions ('Not for the market (market_tokens) or for Earn positions (my_positions)'). When-to-use, when-not, and alternatives are all covered.

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 (readOnly/idempotent/non-destructive) by disclosing the 15-second per-wallet cache, the 1-unit cost, malformed-address refusal, and empty-list behavior for wallets with no Earn history. This is actionable behavioral context an agent needs.

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 core purpose, then uses labeled Returns/Behavior/Errors segments. Every sentence carries distinct information with 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?

With no output schema, the description fully documents the return shape (address, positions[] fields, empty list), behavior, and errors. Nothing an agent needs to invoke and interpret the call 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 with 100% schema coverage, so the schema already documents 'address'. The description adds that a malformed address is refused, which enriches the parameter's expected 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 (reads) and resource (Uniswap v4 positions opened through Earn) and explicitly frames the legacy nature of the product. It distinguishes itself from siblings like my_ladders by naming what it is not for.

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

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

Explicitly says to use it only for wallets known to have used Earn, and routes the agent to my_ladders for current positions and plan_build/plan_ladder for providing liquidity. When-to-use, when-not-to-use, and alternatives are all present.

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 read-only/idempotent/destructive, and the description adds context they cannot: the plan is simulated from the owner and unsigned, must be sent within check.sendWithin, should be re-planned rather than resent after a revert, and consumes agent_quota units. It also enumerates the three refusal conditions (opening fee not covered, no pool to buy a side, quote has no exit), which is exactly the kind of failure disclosure that aids invocation.

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

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

Purpose and the sibling routing are front-loaded, and every clause carries information. The long, comma-spliced return-field enumeration is dense and slightly hard to scan, but with no output schema it is earning its place rather than padding.

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 16-parameter tool with no output schema, the description covers the missing pieces: the returned transaction/check/pool/price structure, the time window, the simulation semantics, quota cost, and the error cases. Nothing an agent needs in order to plan correctly appears to be absent.

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

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

Schema description coverage is 100%, so the schema already carries full parameter meaning and the baseline is 3. The description only echoes a few fields (pool, fee, slippage) via the return summary rather than adding syntax or constraints the schema lacks, so it neither helps nor hurts.

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 precise verb and resource: it plans one (or two) unsigned transactions that buy the missing side, build a ladder in a v4 pool, and open a pool on the hook if none exists. It explicitly names the siblings it supersedes (plan_swap, plan_open_pool, plan_ladder) and the ones it is not for, so an agent can route without opening 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 states the selecting condition directly ('Use whenever the caller pays in ETH or USDG') and gives both exclusions with the correct alternative for each: plan_ladder for assets already held, plan_limit_order for a single-price order. It also notes the USDG two-transaction case (approval first), which is a usage-relevant nuance.

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), yet the description adds substantial context beyond them: the simulation result fields, sendWithin expiry, the instruction to re-plan rather than resend a reverted plan, quota cost, and the specific refusal conditions (no rung, no money side, zero amounts, flagged token). The only redundancy is restating that nothing is signed or sent.

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 the sibling routing before the dense Returns/Behavior/Errors blocks. It is long, but nearly every clause carries operative detail (fee split, expiry, refusal reasons); a small amount, such as the read-only restatement, could be trimmed.

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 17-parameter tool with nested objects and no output schema, the description compensates by enumerating the return payload (transactions[], check, sendWithin, rungs, fees) and the error surface. An agent has enough to invoke and interpret results 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 100%, so the schema already documents each parameter; the description nonetheless adds meaning the schema lacks, notably the rung orientation rule (rungs under the price hold the quote and buy as it falls, over hold the token and sell as it rises) and the fee mechanics. It does not restate the individual optional params, so it stays above the baseline without being exhaustive.

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 ('Plans a ladder, a deposit spread over up to 40 narrow one-sided ranges (rungs) of one pool') with the input source ('assets the wallet already holds') and output form ('unsigned transactions'). It explicitly distinguishes itself from plan_build and plan_limit_order, so an agent can route without opening a schema.

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

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

Gives explicit when-to-use ('wallet holds the token, the quote asset, or both'), when-not ('with only ETH or USDG, prefer plan_build'), and a named alternative for a different shape ('Not for an order at one price (plan_limit_order)'). Nothing about tool selection 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?

Beyond the annotations' readOnly/idempotent hints, it discloses that the plan is built 'from the chain at this block and simulated from the owner', that the caller must 'send it within check.sendWithin', that a reverted plan should be re-planned, and that it 'costs quota units (agent_quota)'. It also lists the precise refusal conditions (not owner, closed ladder, action doesn't fit, delegate lacks permission) – rich disclosure fully consistent with readOnlyHint=true.

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 sequenced sections (Use after, action breakdown, Returns, Behavior, Errors) that are easy to scan. It is dense and long, but nearly every clause carries decision-relevant content, so little is wasted.

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

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

For an 11-parameter, no-output-schema tool this is thorough: it explains the return payload (transactions[], check with ok/failedStep/reason/ethNeeded, sendWithin, ifItReverts, slippagePct, expected amounts, gainCut), error/refusal conditions, quota cost, and simulation semantics. Nothing an agent needs to call it correctly appears missing.

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

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

Schema coverage is 100%, so the per-parameter descriptions already carry most semantics, but the description adds real meaning the schema lacks – the effect of each action enum value, the '5% of the ladder's value' cost of take_nfts, the 'final' nature of give, and what sharePct/slippagePct actually drive in a close.

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 ('Plans one action on a ladder...returns the unsigned transaction') and explicitly enumerates all seven action values with distinct semantics. It also positions itself against the prerequisite sibling by saying 'Use after my_ladders', so an agent can distinguish it from plan_ladder/plan_limit_order 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?

'Use after my_ladders' gives a clear sequencing cue, and each action value is described with its effect, so the agent knows which action to pick. However, it never names an alternative tool to route to (e.g., opening a ladder) nor states when-not to use it; the routing guidance is strong but not complete.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond them: nothing is swapped at placing, the order earns pool fees while filling, part fills are not final and rungs trade back, the keeper closes on full fill, it costs quota units, and it must be sent within check.sendWithin or re-planned. This is rich lifecycle and operational context that annotations 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?

It is long, but front-loaded with purpose and every sentence carries distinct information (mechanics, lifecycle, returns, quota, errors). The return-field enumeration is dense but justified because there is no output schema. Slightly verbose, but no dead weight.

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 15-parameter mutation-planning tool with no output schema, the description supplies the missing return shape (transactions[], check, sendWithin, then), the error/refusal conditions, and the post-placement lifecycle. An agent has everything needed to plan and correctly hand off the unsigned transactions.

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 meaning not in the schema: the acceptBuilt failure path (>1% price move, built prices returned), the default closeOnceFilled keeper rule and the 'then' field that sets it, and the significance of check.sendWithin. It stops short of annotating every one of the 15 parameters, hence 4 rather than 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?

The description opens with a specific verb+resource ('Plans an order at a price and returns the unsigned transactions') and then defines the two modes (limit sell holds over the price, limit buy holds under it). It also names the siblings it is not (plan_ladder, plan_build for a band), so an agent can distinguish it 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?

'Use when the wallet wants to buy or sell at a price, not now; for a band around the price use plan_ladder or plan_build' gives an explicit trigger and explicit alternatives. When-not and error conditions ('refused when the price is on the wrong side of the market') are also 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 readOnly/idempotent/non-destructive, and the description goes well beyond them: the pool holds nothing until liquidity is added, opens at the existing market price, costs about a dollar, is priced from this block and simulated from the owner, consumes agent_quota units, must be sent within check.sendWithin, and should be re-planned rather than resent if it reverted.

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, with clear Returns/Behavior/Errors segments. The long enumeration of return fields is justified by the absence of an output schema, though the prose is run-on in places and could be trimmed slightly.

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 compensates fully by enumerating the return payload, explaining the follow-up (key and price for plan_ladder with newPool), stating quota cost, and listing the three refusal conditions. An agent has everything needed to call and interpret it.

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: the fee is 'taken in the quote,' and the quote parameter must have a 'real exit' (refused under 2,000 USDG of on-chain liquidity), which is a constraint the schema does not state.

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+target: plans a new Uniswap v4 pool for a token on LoomDesk's open hook (LoomOpenHookV2), and names the mechanism (fee split to liquidity vs. book). It is clearly separable from siblings plan_build and plan_ladder, which it references by name.

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

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

Explicit selection rule: 'Use when ladder_pools shows no pool of the token against the quote wanted, or none that pays liquidity,' plus an exclusion routing to plan_build 'when a position is wanted in it right away.' It also enumerates refusal conditions, so the agent knows when this tool will not work.

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, openWorldHint, and destructiveHint=false, but the description adds meaningful context beyond them: it returns unsigned transactions, costs quota units, refuses when no route exists, simulates from the owner, and explains the approval-then-swap sequence. These details make the tool's behavior clear 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?

The description is front-loaded with purpose and usage, then uses labeled sections (Returns, Behavior, Errors) that are appropriate for a tool with no output schema. Although dense, every sentence supplies relevant information and 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?

Given the complex swap-planning behavior, the absence of an output schema, and full parameter coverage by the schema, the description supplies the return shape, simulation semantics, quota cost, error condition, and revert guidance. Nothing material for correct invocation appears to be missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds no additional parameter-level meaning; it restates the swap concept but does not clarify syntax, constraints, or defaults for from, to, owner, amount, or slippagePct beyond what the schema 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?

The description states a specific verb and resource: it plans a swap of one asset for another via an aggregator and returns unsigned transactions. It distinguishes itself from the sibling plan_build by specifying it is for a wallet needing an asset on its own, not for funding a position.

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 an explicit when-to-use condition ('Use only when a wallet needs an asset on its own') and names the alternative plan_build with the condition that selects it. It also includes operational guidance to send within check.sendWithin and to re-plan rather than resend a reverted transaction.

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