ava

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

With no annotations, the description carries the full burden and delivers rich behavioral context: it distinguishes CLAIMED from PROVEN, defines receiptsProven as chain-confirmed, explains that unconfirmed receipts prove nothing, describes AP2 alignment for verification, and clarifies owner vs. stranger visibility. It even addresses the edge case that 'zero is zero, never a placeholder.' This goes well beyond a basic read operation.

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

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

The description is front-loaded with the purpose and use case, then adds precisely the behavioral nuances an agent needs (proof semantics, AP2 alignment, visibility, zero handling). Every sentence conveys a distinct, non-redundant fact; nothing 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?

Despite having no output schema, the description tells an agent exactly what the response will contain and how to interpret it. It covers the return fields, proof semantics, verification compatibility, access control, and numeric edge cases. An agent has everything needed to call this tool and interpret the result 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 both parameters. The description's statement about owner/public visibility mirrors what the userId property already says ('Owner sees the full record; others only a public one'). Thus the description adds no new parameter-level meaning beyond the schema, matching the baseline of 3.

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

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

The description opens with a specific verb and resource ('Read an agent's track record') and enumerates the concrete content returned (mandates, executions, refusals, receipts). It is clearly distinct from sibling tools like ava_get_receipt (single receipt) and ava_list_mandates (list of mandates) because it frames the output as an agent-level record with proof standing.

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

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

The description explicitly states when to use the tool: 'before delegating capital to it.' This is a clear contextual trigger. It does not name alternatives or exclusions, but the use case is specific enough to guide an agent toward this tool rather than similar lookup tools.

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

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

With no annotations provided, the description carries the full burden—and it delivers. It discloses refusal behavior (no funds moved, only a refusal record), testnet vs. mainnet semantics (simulated vs. real signing, fail-closed), and the constraint that it 'never claims a fill it cannot show.' These are behaviors the agent needs to reason about safety and outcomes.

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 and front-loaded with the core purpose, then flows into gating constraints, mode differences, and a critical safety directive. Though long, each sentence carries distinct information (refusal, fail-closed, venue registry, user confirmation). No filler; it reads as a structured warning sheet for a high-stakes action.

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 tool with no output schema, the description covers what to expect on success and failure (receipt vs. refusal record), how to handle modes, and which sibling to consult. It also flags the prerequisite (user confirmation) and the risk of stale preview hashes. This is complete for an approval endpoint that must be invoked correctly to avoid financial consequences.

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 documents each parameter. The description adds flow-level meaning: mode's enum is explained ('Default testnet. Live is fail-closed without a submit path'), executionId is tied to the prior turn, and previewHash is described as binding the signature to the reviewed artifact. This enriches the agent's understanding beyond field-level descriptions.

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 immediately states a specific verb+resource: 'the one call that actually settles a plan from ava_copilot_turn.' This distinct purpose separates it clearly from siblings like ava_preview_tx (preview) and ava_lend_execute (a different execution path). The phrase 'the one call' reinforces its unique role in the approval flow.

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

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

The description explicitly routes the agent: 'Call ava_list_venues for which routes are live rather than assuming' and warns 'NEVER call without explicit user confirmation of the previewed quote.' It also explains when a call might refuse, setting expectations for alternative outcomes. This leaves no ambiguity about when this tool is appropriate.

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 no annotations, the description carries the transparency burden, and it discloses the KYA gate as fail-closed, optional agent credentials, the returned executionId/approve_execute action, and the no-fill behavior. It does not cover error conditions, idempotency, or how mode values like live/mainnet affect the quote, which keeps it from a 5.

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

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

Four compact, information-dense sentences front-load the pipeline and example, then cover output, auth, and the crucial no-fill caveat. There is no filler or repetition of schema-only facts.

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?

The description gives the core interaction loop and return contract, which is sufficient for a basic call. But with no annotations and no output schema, it should clarify mode behavior, portal/userId semantics, and a fuller description of the returned actions/errors; the 'testnet quote' wording is too narrow relative to the mode enum.

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

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

Schema coverage is only 33%, so the description must add meaning; it does so for the required message with a concrete natural-language example and for agentId/agentCredential by explaining the KYA gate. However, mode, portal, and userId are left undefined—mode is especially important given the live/mainnet/testnet enum and the description's 'testnet quote' phrasing.

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 defines a concrete function: a natural-language copilot turn that converts a message into an intent, plan, and quote, returning approve_execute actions with an executionId. The worked example ('Swap 10 USDC to SUI on sui with 50 bps slip') pins down the input style, and the explicit 'Does NOT fill until ava_approve_execute' differentiates it from the execution 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 clear usage context: send a natural-language request to get a plan/quote and actions, and it explicitly establishes the follow-up tool by stating execution does not happen until ava_approve_execute. It does not enumerate alternatives such as ava_plan_workflow or ava_preview_tx, so it stops short of full when/when-not routing.

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?

No annotations are provided, so the description carries the full burden. It discloses that the call does not touch funds, which is a key behavioral trait. It also explains the registration lifecycle (before wallet/mandate), which is useful. However, it does not mention potential side effects like creating database records, or any authorization requirements, but given the scope, this is adequate.

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 concise but packed with information. It front-loads the core purpose and then explains the two modes clearly. It could be slightly more structured (e.g., with bullet points) but is efficient in using words to convey critical distinctions.

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 no output schema and partial parameter documentation, the description covers the essential context: what this tool does, its two usage modes, and its safety profile (no funds touched). It doesn't explain the response format or further steps, but for a registration call, this is reasonably complete.

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

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

Schema coverage is 50% (label and agentId are described in schema, but userId and portal are not). The description adds value by explaining how agentId and label are used in different modes (e.g., byo-external with label for Mode A, defi-* for Mode B). It also clarifies that portal is required but doesn't explain its options, which is a minor gap.

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

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

The description clearly states the tool's purpose: registering an agent instance under a userId before it has a wallet or mandate. It distinguishes two modes (A and B) with specific agentId values and labels, which is very specific and helps an agent understand exactly what this tool does and how it differs from others like ava_create_mandate or ava_provision_wallet.

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

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

The description implies when to use this tool (before wallet/mandate creation) and contrasts with alternatives by mentioning that this call alone never touches funds, suggesting it is not for financial actions. It could be more explicit about when NOT to use it (e.g., if wallet needs provisioning) but the context is clear enough.

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 no annotations, the description carries the full burden, and it excels: it discloses that creating a mandate 'moves no money by itself', is 'not yet signed by an external wallet', and is not a 'user-authorised instruction a stranger can rely on'. It also reveals the crucial downstream gating behavior where ava_approve_execute can refuse based on the mandate's status and constraints.

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

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

The description is front-loaded with the core definition, followed by a helpful example and important caveats. The caveats about not moving money and not being externally signed are verbose but earn their place because they prevent dangerous misinterpretation. The overall structure is clear and each sentence contributes something useful.

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?

The description provides a strong conceptual model and an example, but the tool has 9 parameters, nested objects, no output schema, and no annotations. It does not explain the required 'portal' parameter, the meaning of 'conditions', or what the tool returns. This is a minimally viable definition with clear gaps for a tool of this complexity.

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

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

Schema description coverage is only 11% (only agentInstanceId has a description), so the free-text description must compensate heavily. It does add meaning for objective, capital, constraints, and optional agentInstanceId scoping, and gives a structured capital example {asset, amount, chain}. But most parameters — portal, userId, name, message, conditions — receive no clarification in either the schema or the description, leaving agents to guess their semantics.

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 uses a specific verb and resource: 'Create a capital mandate', and defines exactly what that means — the objective, capital, and constraints an agent is allowed to act under. The example ('Earn on 500 USDC on Base, max 5% drawdown') makes the tool's purpose concrete and unmistakable. It also implicitly distinguishes itself from execution tools by stating it 'moves no money by itself'.

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

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

The description implies when to use the tool by explaining it creates Ava's own record rather than executing an action, and it references the later ava_approve_execute flow. However, it never explicitly says 'use this when you need to define a mandate' or contrasts it with sibling creation tools like ava_create_agent, leaving the when-to-use vs alternatives guidance implicit.

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 absent, the description carries the full burden. It clearly states 'Read-only' and 'Never executes and never moves money,' covering the most critical behavioral trait. It also discloses the optional live-price fetch behavior. The phrase 'record the result' is a bit ambiguous—it might imply a side effect—but it also states 'read-only' which could be interpreted as no persistent state changes. However, the description does not detail error handling, reversibility, or the nature of the recording, so it's not fully transparent but adequate for key safety aspects.

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 three sentences, each serving a distinct purpose: the action, the optional behavior, and the safety contrast. It's front-loaded with the core function ('Read-only: check a mandate's exit conditions...') and then adds nuance. No unnecessary words, and it is well-structured for quick scanning.

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?

While the description covers the essential usage and safety, it lacks details about the snapshot object's structure, the exit conditions logic, and the output format (especially since there is no output schema). It does not mention prerequisites like wallet existence or error scenarios, making it incomplete for a tool with an optional complex parameter. The description is sufficient for selection but not for full invocation understanding.

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 has 0% description coverage, so the description must clarify parameters. It does: 'snapshot' is explained as a market snapshot and its omission triggers a live CoinGecko price for the condition asset. 'mandateId' is implicitly the identifier of the mandate being checked. This adds semantic meaning beyond the bare schema, though it doesn't specify the snapshot object's internal fields or formats, which would be more detailed.

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

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

The description clearly states the verb 'check' with the resource 'mandate's exit conditions' and the action of recording the result. It also explicitly distinguishes itself from ava_approve_execute by stating 'ava_approve_execute is the only tool that does [execute/move money].' This differentiates it from siblings and leaves no ambiguity about its core function.

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

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

The description provides explicit usage guidance: it explains that omitting the snapshot pulls a live CoinGecko price, indicating when to include or exclude that parameter. It also gives a clear when-not-to-use statement: 'Never executes and never moves money' and points to ava_approve_execute as the alternative for execution. This is direct and actionable.

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 no annotations carrying safety or behavioral signals, the description does the full job: it states the return payload, defines the proof.standing enum, warns that a verified receiptHash is not sufficient evidence of chain confirmation, and discloses owner-scoped access plus a credential-free verify URL. That is unusually rich behavioral context for a read tool.

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

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

The purpose is front-loaded in the first sentence and the rest of the paragraph delivers high-value caveats. The text is slightly dense and mixes enum definitions, access control, and verification guidance in one run-on paragraph, so it is informative but not optimally structured.

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?

Even without an output schema, the description covers what is returned, how to interpret the proof.standing field, the critical verified-vs-chain-confirmed distinction, and the access model. For a two-parameter read tool with no annotations, nothing essential is missing.

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

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

The schema already describes both parameters with 100% coverage, so the baseline is 3. The description adds meaning by tying executionId to the output of ava_copilot_turn/ava_approve_execute, explaining that userId is only needed for headerless callers, and clarifying ownership semantics, which exceeds 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?

The description opens with a specific verb and resource: retrieving the receipt for a prior ava_approve_execute by executionId. It also frames the tool's position in the workflow ('the loop's final step'), which distinguishes it from the execution and planning siblings.

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 clearly situates the tool after ava_approve_execute and gives the exact identifier to use, so when to call it is evident. It does not explicitly name alternatives or exclusions beyond the owner-scoping constraint, so it stops short of a full when-versus-other-tools guide.

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 no annotations provided, the description carries the full burden of behavioral disclosure, and it meets it thoroughly. It explains the two-phase approval requirement, that the agent's call is never treated as human confirmation, and the critical return contract: only a settlement verified against the venue's on-chain event yields a txHash, otherwise no txHash field exists, preventing drafts from being narrated as fills.

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 information-dense, and every sentence serves a purpose. It front-loads the core purpose ('Execute a REAL lend') and then systematically covers routing, provenance, the two-phase design, and return behavior. It is appropriately sized for the tool's complexity; while not terse, it avoids redundancy.

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 no output schema and no annotations, the description must fully specify call behavior and return semantics, and it does. It explains the two-phase protocol, the absence of a txHash for drafts, the per-route refusal behavior, and the exact rules for venue selection and idempotency keys. Nothing an agent needs to correctly invoke the tool 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 75%, so the baseline is 3, but the description adds meaningful context beyond the schema for several parameters. It explains the venue parameter's default behavior and refusal semantics, details the previewHash lifecycle, and clarifies the idempotencyKey requirement for the compound route, including why a fresh key on retry defeats single-flight protection. This elevates it above baseline.

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

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

The description states a specific verb and resource: it executes a real lend against a mandate. It immediately distinguishes itself from siblings by declaring it is the only MCP tool that moves live capital, and it details the exact venues and their provenance. This unambiguously differentiates it from the 14 sibling 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?

The description gives explicit when-to-use guidance: it is the only tool for executing real capital moves, and it details the two-phase invocation pattern (call without previewHash, then with). It also warns against describing unproven routes as proven and clarifies that operator-disabled routes refuse at the capability gate, so an agent knows whether a call will succeed.

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 no annotations, the description carries the full burden. It states a read operation ('List') but does not disclose potential side effects, permissions, rate limits, or behavior in edge cases (e.g., empty results). The description is minimal and leaves behavioral aspects largely unspecified.

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

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

The description is a single, well-structured sentence that conveys the essential purpose without unnecessary verbosity. It is concise and to the point, though its brevity sacrifices detail for clarity.

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 4-parameter schema, no annotations, and no output schema, the description is insufficient. It omits explanations for half the parameters and provides no information about the return format or any constraints. An agent would likely need additional context to use this tool correctly.

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

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

The description explicitly mentions only two of the four parameters: userId and agentInstanceId. It does not explain the purpose or allowed values for 'portal' and 'status', which are also in the schema. This incomplete coverage fails to clarify the role of each parameter, especially since none have descriptions in 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?

The description clearly states the action ('List'), the resource ('capital mandates'), and the primary scope ('for a userId'). It also mentions an optional filter by agentInstanceId, making the core purpose evident. However, it does not elaborate on what 'capital mandates' entails, which could be ambiguous in some contexts.

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

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

The description does not provide any guidance on when to use this tool versus alternatives, such as the sibling tools listed. It merely states what it does without contextual cues for selection, leaving the agent to infer appropriate usage from the tool name alone.

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 no annotations, the description carries full responsibility for behavioral disclosure. It clearly states that the tool returns an unsigned envelope, that authorization only occurs after user signature, and that missing bounds are returned in 'missing' and block signing. It also explains the minGainBps requirement to prevent the agent from choosing financial thresholds. These are meaningful, non-obvious behaviors fully 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?

The description is long (around 200 words) but every sentence adds value: it explains the concept, contrasts with a sibling, lists the bounds, explains the missing-field behavior, and justifies minGainBps. It is front-loaded with the core purpose, and while verbose, it is efficiently organized without redundancy.

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?

The description covers all critical aspects for correct invocation: what it does, when to use it (vs. workflow), what inputs are expected (message content), what happens with missing info, and the authorization flow. It also explains a non-obvious parameter requirement. No crucial information seems absent for an agent to correctly call this tool.

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

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

Schema coverage is 67%, leaving one parameter without a description (userId). The description adds critical context for minGainBps ('required from you because users say the best yield rather than a basis-point floor') and interprets the 'message' parameter as containing the cadence and bounds. It does not explain userId further, but that parameter's purpose is self-evident from its name. The description compensates for the coverage gap by providing richer semantic context for the key parameters.

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 ('turn a request for REPEATED autonomous action into an envelope of bounds'), names the resource (an envelope of bounds), and explicitly contrasts with ava_plan_workflow. It clearly differentiates from sibling tools by focusing on cadence-driven actions.

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

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

The description explicitly says 'Use this instead of ava_plan_workflow when the request describes a cadence,' providing a direct alternative and selection condition. It also explains the underlying rationale (approving each rotation defeats the point), leaving no ambiguity about when to pick this tool.

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

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

With no annotations, the description carries full burden and does an excellent job. It discloses side effects ('Signs nothing and moves nothing'), error handling ('Plans nothing it cannot execute... comes back in unsupported with a reason'), and output expectations ('Every leg reports executable'). It also explains how dependencies are built (third leg depends on second, amount from actual delivery). This is comprehensive and directly address what an agent needs to know.

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 lengthy but every sentence adds value: it front-loads the core purpose, gives a concrete example, explains dependency handling, and states limitations. It could be tightened, but it is well structured and not redundant, earning a 4 rather than a 3.

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 no annotations and no output schema, the description is thorough. It explains the type of request, dependent leg construction, cross-chain support, unsupported cases, and output fields (executable). While it doesn't provide a full response schema, it gives enough for an agent to call it correctly and interpret the result, which is strong for a complex tool.

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

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

Schema coverage is 50% (only message is described in the schema, with 'The user's request, verbatim. Do not pre-parse it.'). The description adds context about what the message should contain (DeFi request) and gives examples, but it does not add anything about userId, which remains unexplained in both the schema and description. Thus the description compensates for message but not for the undocumented parameter, landing at a baseline 3.

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: 'Turn ONE natural-language DeFi request into the dependent actions it actually contains.' The description immediately distinguishes it from execution tools by noting it 'Signs nothing and moves nothing,' and the examples clarify the cross-chain dependency modeling. It is clearly differentiated from siblings like ava_lend_execute or ava_approve_execute.

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

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

Explains when to use it: for breaking a single complex request into dependent executable steps, including cross-chain. It implies it is the planning step before execution, and explicitly states it does not sign or move funds, which signals it is not for execution. However, it does not explicitly name alternatives (e.g., ava_plan_standing) or state conditions for when not to use it, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses key behaviors: it returns seeded balances and fills, is testnet-based, and does not invent live chain balances. It does not explicitly state read-only behavior, but the nature of a portfolio query implies it. The absence of an explicit read-only declaration and lack of side-effect disclosure are minor gaps.

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 extremely concise, with two sentences that pack purpose, scoping, data content, and a key constraint. The most important information (simulated testnet portfolio) is front-loaded, and every word contributes value without redundancy.

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

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

For a simple read-like tool with fully documented parameters and no output schema, the description provides sufficient context: it mentions seed data, testnet nature, and the no-live-invention constraint. It could be improved by explicitly stating the expected output format, but referencing GET /v1/portfolio gives a strong hint. Overall, it is adequately complete for an agent 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% for both parameters (portal and userId), each with descriptions. The description adds little beyond confirming userId is required and portal is optional, which is already in the schema. It does not provide additional semantic detail for parameters, so baseline of 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 clearly states a specific purpose: it returns a simulated testnet portfolio for a userId, with the same data as GET /v1/portfolio. It distinguishes itself from siblings (which are action-oriented tools) by being the only portfolio query. The phrase 'Does not invent live chain balances' further clarifies its 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?

The description gives clear context that this is for testnet/simulated data and clarifies it does not fabricate live balances, which implies when to use it. However, it does not explicitly name alternatives or state when not to use it beyond the testnet scope. Since siblings are clearly different action tools, the guidance is adequate but not 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?

With no annotations, the description carries full behavioral burden and succeeds. It discloses the operation is side-effect-free ('Nothing is signed or submitted'), notes simulation is conditional ('simulate it where supported'), and reveals the return contract implicitly via 'previewHash'. This exceeds typical transparency and provides safety guarantees 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?

Three sentences, each purposeful: first defines action and inputs, second enforces safety, third instructs downstream workflow. Front-loaded with the tool's identity ('Pre-sign preview') and zero filler. Every clause adds critical nuance without bloat.

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 preview tool with no output schema, it covers the essential flow, return key (previewHash), and human-in-the-loop requirement. Missing details like error cases or edge conditions when simulation isn't supported, but the core workflow is fully specified. Given the multi-chain complexity and lack of annotations, this is strong but not perfect.

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 covers 67% of params with executionId and portal described. Description mentions 'pending plan' and 'provisioned Turnkey wallet,' which adds minimal disambiguation, and references the prior ava_copilot_turn step for executionId. However, it does not clarify userId or explain parameter relationships beyond the flow. Adequate but does not fully compensate for the missing schema description.

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?

Uses specific verbs and resources: 'build the exact venue artifact... return it UNSIGNED' and names concrete artifact types (CoW EIP-712 order or unsigned Solana transaction). Clearly distinguishes itself from sibling ava_approve_execute by framing itself as the pre-sign step. No ambiguity about what tool does.

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

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

Explicitly states when to use: 'Pre-sign preview' and provides sequencing ('pass the returned previewHash to ava_approve_execute'). Sets boundaries with 'Nothing is signed or submitted,' and indicates the when-not-to-use by routing the actual signing to a sibling. Gives clear user responsibility ('Show the artifact to the human').

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 no annotations provided, the description carries the full burden and does so thoroughly: it discloses side effects, non-money-movement, the pending_provision fallback when Turnkey is not configured, and the fact that a pending wallet cannot sign or hold funds. This is strong behavioral disclosure beyond the bare minimum.

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 three focused sentences with no filler. It front-loads the core action, then covers prerequisite, return purpose, exclusions, and a key failure mode. Every sentence contributes meaning.

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 small parameter set, no output schema, and no annotations, the description is remarkably complete: it covers prerequisite, input scope, return value, what the tool does not do, and the pending_provision behavior. An agent has enough context to select and call the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It explicitly references userId and family, and enumerates the allowed family values. It could add a bit more about userId format or wallet family implications, but it gives enough semantic grounding for an agent to invoke correctly.

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 ('Provision'), a concrete resource (Turnkey-custodied wallet address for a userId), and a scope constraint (one chain family: evm, solana, sui). It clearly differentiates the tool from siblings by noting it does not fund or move money.

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

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

The description clearly establishes a prerequisite ('Requires ava_session first') and states what the tool is for versus what it explicitly does not do ('does not fund the wallet and does not move any money'). It does not name alternative sibling tools for when to use them instead, but the usage context is still 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?

No annotations are provided, so the description carries the full burden. It discloses important side-effect boundaries: 'Moves no money and provisions no wallet by itself' and 'create or resume' implies persistence of identity. It also advises to reuse the returned userId, reducing redundant calls. It does not, however, detail what exactly 'create' entails (e.g., whether it writes to persistent storage) or any auth requirements.

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

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

Three sentences with no filler: purpose, call order, and side-effect exclusions are front-loaded. Every sentence adds value and the structure flows logically from 'what' to 'how/when'.

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 only 2 optional parameters and no output schema, the description fully covers what an agent needs: how to start (create/resume), when to call (first in loop), and how to use the result (reuse userId). It even clarifies non-effects (no money, no wallet). There is no missing critical detail for successful invocation.

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 property descriptions are sparse (only userId has one) and coverage is 50%. The description explains the meaning and reuse of userId ('reuse the returned userId on every other tool') but does not clarify displayName's purpose or expected format. Since the schema alone doesn't document displayName, this is a gap the description fails to fill.

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: 'Create or resume a human/org identity (userId)' and positions it as 'the first call in the loop'. It also distinguishes itself from siblings by noting 'Moves no money and provisions no wallet by itself', which differentiates it from money/wallet tools in the sibling list.

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

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

The description gives explicit when-to-use guidance: 'the first call in the loop' and 'call once and reuse the returned userId on every other tool'. It also implies not to use it for money or wallet operations, saying it 'moves no money and provisions no wallet by itself'. This is clear and actionable.

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