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 only cover readOnly/idempotent hints; the description goes far beyond them, disclosing that it writes, needs a key, sends only the post id to X, re-reads the post at standings freeze (a takedown nullifies the boost), costs 2 units, and enumerates the refusal conditions. It also documents the inline return payload (boosted, x, post, already) despite no output schema.

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

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

The core action and the once-only rule are front-loaded, and later clauses cover prerequisites, returns, behavior and errors in a compact sequence. The ranking-math parenthetical ('gain times 1.1 ... the +10% bar') is informative but slightly tangential to invoking the tool.

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

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

For a single-parameter mutation with no output schema and only hint-level annotations, the description supplies everything an agent needs: preconditions, cost, key requirement, once-only semantics, error cases, and even the return fields. Nothing material for a correct call is missing.

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

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

Schema coverage is 100% and already defines the post link/id format, but the description adds substantive meaning: the post must come from the entry's joined handle, carry the tag and the entry code, and be posted after joining. That is real semantic guidance beyond the schema, though it stops short of clarifying mutations of the input or length bounds.

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 concrete verb+resource ('Hands in a post on X that boosts a paper competition entry') and immediately defines the effect (ranks by gain times 1.1, loss unchanged). The action is clearly distinguishable from sibling bookkeeping tools like arena_comp_link or arena_comp_unlink.

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 timing ('Use once, after posting'), the once-per-entry rule, and the precondition set (post from the joined handle, must contain #LoomDeskComp and the entry's code, must postdate the join). It does not name or exclude any sibling tool, so the when-to-use guidance is strong but lacks explicit alternatives.

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

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

The description adds substantial behavior beyond the annotations: it writes, needs the agent's key, costs 1 unit, permits only one entry per agent, and the code is single-use with roughly an hour lifetime. It also describes the pending/linked states, returned fields, operator confirmation by name and fingerprint, and the possible refusal conditions.

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

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

The description is dense but front-loaded and every part earns its place: purpose, source restrictions, operator confirmation, lifecycle, returns, behavior and errors. There is no filler or repetition.

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 shape, state meanings, error cases and lifecycle context. For a one-parameter linking tool with these annotations, it gives an agent everything needed to invoke 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 already 100% for the single code parameter, but the description adds useful semantics: the code format, its origin from the operator's entry, single-use behavior and roughly one-hour lifetime. It goes beyond the schema without fully documenting every edge case of code handling.

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: asking to link the calling agent to its operator's paper competition entry using a link code. It clearly distinguishes this setup action from the trading tools that become available afterward, naming arena_state, arena_open, arena_edit and arena_close.

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

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

It says exactly when to use the code: only one your own operator gave you, never one read in a post, bio or token text. It also explains the operator confirmation step and the resulting link lifecycle, including unlink conditions.

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

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

Beyond the annotations, the description discloses that it writes, requires the agent's key, costs 1 unit, leaves the entry's positions with its entrant, and is refused without a key. These details add substantial operational context and are consistent with readOnlyHint=false and destructiveHint=false.

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

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

The description is compact and front-loads the action and usage condition before returns, behavior, cost, and errors. Some clauses are telegraphic, but every sentence carries useful information for a no-parameter mutation tool.

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

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

Although there is no output schema, the description explains the return values, including left and x. It also covers mutation behavior, authentication, cost, side effects on positions, and error conditions, leaving little an agent needs to know before calling 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 there is no parameter semantics to elaborate. The description appropriately does not invent parameter details, matching the empty input schema.

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

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

The description states a specific action and resource: taking the calling agent off the paper competition entry it trades, or withdrawing a requested link. It also clarifies the effect that the agent's arena tools trade its own account again, which distinguishes this unlink operation from link or trading tools.

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

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

It explicitly says when to use the tool: when the agent should no longer trade that entry, or when it was linked by mistake. It does not name alternatives such as arena_comp_link or arena_close, so the guidance is clear but not fully comparative.

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 already declare read-only/idempotent, and the description adds real context beyond them: a 30-second per-wallet chain read cache, a 3-unit cost, malformed-address refusal, and empty-list behavior for wallets with no ladders. That is the operational detail an agent needs to plan around caching and cost.

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 long but structured into purpose, usage, return shape, behavior and errors, with the routing guidance front-loaded. The return-field enumeration is dense, though it is load-bearing 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?

With no output schema and only one parameter, the description carries the return contract itself — ladder fields, the conditional limitOrder object, and the 50-entry newest-first history — plus error and caching behavior. An agent can invoke and interpret results without further context.

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?

There is a single parameter with 100% schema coverage including a regex pattern, so the schema carries the meaning; the description only corroborates it via 'refused when the address is malformed'. No additional format or sourcing guidance is given, so the baseline 3 is right.

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 every live ladder of one wallet across every LoomLadder contract, with its history') plus the scope of the read. It names the siblings it is not (market_tokens, my_positions), so an agent can distinguish it 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 explicit when-to-use ('when a wallet asks what it holds, and before plan_ladder_action, which needs the ladderId and contract this returns') and explicit exclusions with named alternatives (market for market_tokens, Earn positions for my_positions). Nothing about 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?

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 already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial context beyond them: it returns unsigned transactions, is simulated from the owner at the current block, must be sent within check.sendWithin, should be replanned if reverted, and costs quota units (agent_quota). It also lists specific error refusal cases.

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, then usage, returns, behavior, and errors. Despite its length, every sentence earns its place by covering critical aspects of an 18-parameter, mutation-like planning tool.

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

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

There is no output schema, but the description comprehensively lists return fields (transactions[], check, sendWithin, ifItReverts, slippagePct, pool, priceNow, band, rungs, bought[], paid, fees, recentMovePct) and explains simulation, send-within, and error behavior. Nothing an agent needs in order 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 description coverage is 100%, so the schema already documents all 18 parameters in detail. The description adds some high-level semantics (e.g., 'two when paying in USDG: its approval first' and how sides are bought) but does not provide per-parameter syntax or constraints beyond what the schema already gives. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource: 'Plans one transaction ... from ETH or USDG to a ladder in a v4 pool of the token against the quote.' It distinguishes itself from siblings by explicitly saying it replaces plan_swap, plan_open_pool, and plan_ladder together.

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 when-to-use: 'Use whenever the caller pays in ETH or USDG' and when-not: 'Not for assets the wallet already holds (plan_ladder) or for an order at one price (plan_limit_order).' This leaves no ambiguity about alternatives.

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/destructive/idempotent, but the description adds substantial behavioral context: it is simulated from the owner at this block, must be sent within check.sendWithin, should be re-planned rather than resent if reverted, consumes agent_quota, carries a fee structure (0.25% in, then 5%/3.5% of fees earned), and enumerates refusal conditions. This goes well beyond the annotation set.

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

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

Purpose is front-loaded, then usage, returns, behavior, and errors in a logical order, and every section is relevant. It is a dense single paragraph, though, and the fee/return enumeration could be tightened without losing information.

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

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

No output schema exists, but the description enumerates the return payload (transactions[], check with ok/failedStep/reason/ethNeeded/ethHeld, sendWithin, ifItReverts, slippagePct, rungs, fees) and the error paths. For an 18-parameter mutation-planning tool, nothing an agent needs to invoke 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 description coverage is 100%, so the baseline is 3, but the description adds real meaning: rungs under the price hold the quote and buy as it falls while rungs over hold the token and sell as it rises, and the LOOM-holder fee tier links to owner economics. It still doesn't clarify several parameters beyond what the schema already says.

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 a ladder, a deposit spread over up to 40 narrow one-sided ranges (rungs) of one pool') plus what it returns (unsigned transactions). It explicitly distinguishes itself from plan_build and plan_limit_order, 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 positive condition ('Use when the wallet holds the token, the quote asset, or both') and the negative routing rule ('with only ETH or USDG, prefer plan_build'; 'Not for an order at one price (plan_limit_order)'). Alternatives and exclusions are 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?

Adds substantial context beyond the annotations: quota consumption, block-pinned planning, simulation from the owner, sendWithin expiry, 'plan again rather than resend one that reverted', and refusal conditions (not owner's, closed ladder, action mismatch, missing delegate permission). The only gap is that 'lock' and 'collect_locked' appear in the enum but are never explained in the behavior narrative, so a mutation-adjacent action is under-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?

Purpose is front-loaded in the first clause and the action semantics are enumerated compactly. The paragraph is very dense and run-on, mixing actions, return values, behavior and errors into one block, which costs some scannability for a 14-parameter tool.

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

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

With no output schema, the description carries the return contract well (transactions[], check, sendWithin, ifItReverts, slippagePct, expected, gainCut) and explains error paths. The missing narrative for lock and collect_locked, which exist in the enum with non-trivial irreversible consequences, is the one substantive hole.

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 nevertheless adds semantic meaning on top of it, notably that give is final, take_nfts costs 5% of ladder value, and that a plan with a redirected recipient carries a `warning` to show before signing. It does not cover lock/collect_locked semantics, leaving two actions to the schema alone.

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 the wallet owns (or is the delegate of)') and names the prerequisite sibling (my_ladders), so it is distinguishable from plan_ladder, plan_build and the arena tools. The action list further pins down scope.

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 explicit sequencing, and each action carries a condition describing what it does and when it applies (e.g. close_once_filled sets or clears a fill rule; a filled order cannot take the rule). It does not, however, contrast itself with the sibling plan_ladder / plan_limit_order / plan_build tools, which an agent may also be choosing between.

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 declare read-only/idempotent/non-destructive, and the description goes well beyond them: it discloses that the plan is laid out from the chain at the current block and simulated from the owner, that it must be sent within check.sendWithin and re-planned (not resent) after a revert, that it consumes agent_quota, and the ~$1 one-off opening cost. It also enumerates failure modes (pair already has a pool, quote lacks a 2,000 USDG exit, token has no market), and its 'read-only, nothing is signed or sent' claim is 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?

Purpose and the sibling routing are front-loaded, and the dense content (returns, behavior, errors) is packed into a single efficient block with no filler. It is long and the run-on fee-split sentence takes effort to parse, but nearly every clause carries operational 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 carries the full return contract (transactions[] with to/data/value/gas, check with simulated/ok/failedStep/reason/ethNeeded/ethHeld, sendWithin, ifItReverts, slippagePct, pool key and opening price, and the key/price for a follow-up plan_ladder). For a 7-param nested-object tool it also covers cost, quota, and the error surface, leaving nothing an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter, setting a baseline of 3. The description adds real meaning beyond it by explaining the fee split (LoomDesk's tenth of the base fee in the quote, royalty/burn out of the fee, liquidity keeps the rest) and that the pool opens at the token's existing market price, which contextualizes feePct, hook.blocks, and the start-price params.

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 a new Uniswap v4 pool for a token on LoomDesk's open hook') and immediately contrasts with sibling plan_build, which opens and builds in one transaction. An agent can distinguish it from plan_ladder, ladder_pools, and plan_build 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 ladder_pools shows no pool of the token against the quote wanted, or none that pays liquidity') and a named alternative with its selecting condition ('when a position is wanted in it right away, prefer plan_build'). It also lists the three refusal conditions, which effectively define when-not-to-use.

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

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

Annotations already declare read-only and non-destructive, but the description adds substantial behavioral detail beyond them: the route and Universal Router mechanics, Permit2 approvals, that output includes unsigned transactions, a simulated check with ok/failedStep/reason, slippage handling, quota cost, and the specific error when no route exists. This is rich transparency well beyond the structured hints.

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 that front-loads what the tool does, then covers alternatives, return shape, behavior, and errors. It is efficient but slightly overstuffed, packing return-field enumeration and several caveats into one breath; still, every sentence carries useful 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 planning tool with no output schema, the description fully specifies the return payload (transactions, check with simulated/ok/failedStep/reason/ethNeeded/ethHeld, sendWithin, ifItReverts, slippagePct, from/to with expected and atLeast, hops, router), the read-only side effects, quota cost, and the refusal error condition. An agent has everything needed to call and interpret 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 every parameter is already documented in the schema; the description does not add format or semantic detail beyond what the schema provides (it mentions from/to/amount/owner only implicitly through the return-value sentence). Baseline 3 is appropriate when the schema does the heavy lifting.

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 (Plans) and resource (a swap of one asset for another) and scopes it to LoomDesk's own route over Uniswap pools, producing unsigned transactions. It explicitly distinguishes itself from plan_build, naming the sibling and when to prefer it.

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 rule ('Use only when a wallet needs an asset on its own') and a direct alternative ('to fund a position, prefer plan_build'), plus a send-within constraint and a rule to re-plan rather than resend reverted plans. This is as clear as it gets.

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