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

Beyond the annotations, the description discloses that the tool makes a network request, reserves the caller's single active legacy session slot, creates no blockchain transaction, and never signs or submits. This is valuable behavior context and does not contradict the readOnlyHint=false/idempotentHint=true 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?

Three sentences, each earning its place: core purpose, usage/alternative, and behavioral caveats. It is front-loaded with the most important information and contains 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?

For a create-style tool with five required parameters and no output schema, the description still covers the essential selection, invocation, and safety context: prerequisites, alternative, slot reservation, and the no-transaction guarantee. Nothing needed to select or invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters in detail. The description adds contextual expectations like the quote being 'fresh' and v1, but it does not need to carry parameter-level semantics because the schema is complete.

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 leads with a specific verb and resource: 'Lock one fresh legacy assetfare_quote into a wallet-bound v1 execution session.' It clearly defines what the tool does and explicitly distinguishes it from the v2 session tool, so an agent can differentiate it from 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 states the precondition ('Use only after legacy wallet authentication'), the intended workflow (Solana-SOL to Base/Arbitrum-ETH), and names the alternative for v2 quotes (assetfare_v2_session_create). This gives explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description's statement 'Makes a network request and consumes login-challenge state, but never signs or submits' adds valuable context beyond the annotations—specifically clarifying non-idempotency and non-destructive behavior. It also flags the output as 'sensitive', which is not in the annotations. This is strong added value, though it doesn't detail error or token-expiry behavior.

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

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

The description is two sentences with zero waste: the first sentence states purpose and output, the second provides usage constraints and side effects. It is front-loaded with the core action and uses phrasing that directly guides the agent 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?

Despite having no output schema, the description mentions the returned output ('sensitive wallet-bound access token'), the network request, state consumption, and the exact conditions for use. For a four-parameter authentication tool with clear annotations and schema coverage, nothing essential 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?

With 100% schema coverage, all four parameters (signature, challenge_id, source_wallet, terms_version) are already well-documented in the schema with type, constraints, and guidance. The description adds no additional parameter semantics beyond restating the legacy context; it does not compensate for any schema gaps because there are none. 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 clearly states 'Verify the caller's signature over the exact legacy login challenge and return a sensitive wallet-bound access token,' which specifies a specific verb, resource, and outcome. It further differentiates itself from siblings by explicitly naming the prerequisite (assetfare_start_wallet_auth) and excluding v2 sessions, transaction signatures, and arbitrary messages.

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 commands 'Use only after assetfare_start_wallet_auth' and lists what not to use it for ('v2 session, transaction signature, or arbitrary message'), providing clear positive and negative use cases. This leaves no ambiguity for an agent choosing between this and the many sibling 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description reinforces this by stating it never creates state, signs, or submits, and adds that it reads an Ed25519-signed manifest and safety-bundle binding, plus the 'call once' guidance which implies idempotency. This adds value beyond the annotations without contradicting 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?

The description is two sentences, front-loaded with the core purpose and followed by a concrete usage example. Every sentence contributes meaningful information without redundancy, and the structure is clean and scannable.

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-only tool with no parameters and an existing output schema, the description is complete. It explains what the tool reads, when to call it, and its safety guarantees. The presence of an output schema means the description need not detail return values, and the guidance covers the essential usage 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?

The tool has zero parameters, so the input schema is trivially covered (100%). The description provides no parameter details because none exist, and per the baseline for 0-parameter tools, this is appropriate. No further explanation is needed.

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 reads an Ed25519-signed release manifest and safety-bundle binding, which is a specific verb-resource pair. It distinguishes itself from siblings by emphasizing it's a verification step before preparation, and explicitly notes it never creates state, signs, or submits. However, it does not name any sibling tool to contrast with, so differentiation is implicit rather than explicit.

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: call this before preparing an action and once to verify current release and contract pins. It implies the tool is a prerequisite step and safe to use repeatedly, but it does not explicitly state when to avoid using it or mention alternative tools. The guidance is useful but not exhaustive.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable context beyond annotations by stating 'Makes a network request but never signs or submits' and 'advance the session record', clarifying the mutation nature and the non-signing/submitting behavior. This is useful supplementary detail, though not exhaustive (e.g., no mention of error handling or side effects).

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

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

Two concise sentences with zero waste. The purpose is front-loaded, followed by usage guidance and a behavioral note. Every sentence earns its place, and the structure is immediately scannable.

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 the core purpose, usage constraints, and behavioral transparency. It does not explicitly describe return values or error conditions, but given the tool's role (verify and advance session), the description is sufficient for an agent to call it correctly. Minor gap is the lack of mention of what happens on verification failure, but this is not critical.

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 all four parameters are already well-documented in the schema. The description does not add significant meaning beyond what the schema provides; it merely refers to 'caller-submitted legacy v1 burn' which aligns with burn_signature. Per the baseline for high coverage, a 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 ('Verify' and 'advance') with a clear resource ('Circle attestation and the forwarded Base or Arbitrum USDC mint for a caller-submitted legacy v1 burn'). It explicitly distinguishes itself from sibling tools by naming assetfare_read_session for inspection without advancement and a v2 observe tool for v2 routes, so an agent can easily tell them apart.

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?

Provides explicit when-to-use ('Use only after the CCTP burn is submitted') and names alternatives with their conditions ('use assetfare_read_session for inspection without advancement and a v2 session observe tool for v2 routes'). This leaves no ambiguity about when to invoke this tool versus siblings.

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 discloses meaningful side effects beyond the annotations: 'Makes a network request and advances session state, but never signs or submits.' This tells an agent exactly what state impact to expect and what side effects are excluded. It is consistent with the annotations, and nothing in the description 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?

Three sentences with distinct jobs: first states purpose, second states usage and alternatives, third states behavioral side effects. There is no filler, and the most decision-relevant information is front-loaded.

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

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

The definition covers purpose, sequencing, alternatives, side effects, and parameter semantics comprehensively. The only minor gap is that it does not indicate what the verification result or finalization output looks like, and with no output schema present the description could carry that burden more fully.

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. The description does not add parameter-level detail beyond the schema, but the schema already documents formats, sensitivities, and version constraints for all four parameters, so no compensation is needed.

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: 'Verify an already-submitted destination UserOperation receipt and finalize the legacy v1 workflow record.' It clearly identifies the operation's scope and workflow version, and explicitly names the sibling tool it is not, assetfare_v2_session_observe_output, making differentiation immediate.

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 an explicit sequencing precondition: 'Use only after the caller independently submits assetfare_prepare_destination_action.' It also names the v2 alternative explicitly, and the schema reinforces that the session_id and access_token are legacy-v1-only. This is unambiguous when-to-use guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: it requires caller approval, advances preparation state, and explicitly does not receive the private key, sign, or submit. This is useful for an agent deciding whether this is the right mutation step. It does not describe the response shape, but no output schema exists and the core behavioral traits are well covered.

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-loaded: it states the core action first, then usage constraints, then exclusions. Every sentence earns its place, and the sibling differentiation is woven in 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 4-parameter tool with no output schema, the description covers the action, the workflow context, the v2 alternative, the caller-approval requirement, and the non-goals (no private key, no signing, no submission). The only minor gap is that it does not describe what the response contains or how to detect success, but the description is otherwise complete enough for an agent 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 description coverage is 100%, so the schema already documents all four parameters. The description adds value by clarifying the event_signer_public is caller-generated and ephemeral, and by reinforcing that the private key must never be sent. It also clarifies the access_token is legacy v1 wallet-bound and not a v2 capability. This goes beyond the schema's field 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 states a specific verb ('prepare'), a specific resource ('unsigned CCTP burn'), and the exact context ('current legacy v1 session using a caller-owned event signer public key'). It also explicitly distinguishes itself from v2 sibling tools, so an agent can tell it apart from assetfare_v2_prepare and assetfare_v2_session_create 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?

The description gives explicit when-to-use guidance: 'Use only when the legacy workflow reports this as the next action' and explicitly names alternatives for v2 routes. It also states what the tool does not do (never receives the private key, signs, or submits), which helps an agent avoid misuse.

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 explains that calling this tool 'Makes a network request and advances preparation state, but never signs or submits.' This is valuable safety-relevant context for a settlement tool. It doesn't contradict the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), though it could say more about the exact state changes.

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

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

Three short sentences pack the action, the exact trigger condition, the v2 alternative, and the network/state/signing boundary with zero fluff. The most important information is front-loaded in the first sentence.

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 complex state-advancing tool, the description covers when to call it, the alternative, the scope, and the safety boundary, while annotations plus 100% schema coverage handle idempotency and parameters. It does not explicitly describe the return value, which is a small gap given there is no output schema.

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 all three parameters are fully documented in the schema. The tool description does not need to add param-level meaning; it correctly relies on the schema and provides no additional parameter semantics beyond it.

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

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

The description names a specific verb-resource pair: 'Prepare the exact-cap permit and unsigned ERC-4337 destination settlement plan' for the legacy v1 session. It is explicitly scoped to the destination step and distinguishes from v2 by naming v2 sessions' current action exposure, so an agent can disambiguate among the 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?

It gives an explicit condition: 'Use only when the legacy workflow reports the destination step and after caller approval.' It also names the alternative for v2 sessions (assetfare_v2_session_get), giving clear routing guidance and an exclusion.

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 indicate it is not read-only, not destructive, and idempotent. The description adds that it 'makes a network request and advances preparation state, but never signs or submits,' which clarifies the side-effect profile and the non-submission guarantee. This adds value beyond annotations, though it doesn't cover error behavior or return details.

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

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

Two sentences with no redundancy. The main purpose is front-loaded, followed by usage constraints and behavioral notes. Every sentence 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?

The description covers prerequisites, alternatives, side effects, and what it does not do (sign/submit). The only gap is that it does not describe the return value or output format, which is notable since there is no output schema. Still, for a state-advancing step in a flow, the description is largely sufficient.

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

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

Schema coverage is 100% and both parameters have detailed descriptions in the schema itself. The tool description does not add parameter-specific meaning, but the schema already does the heavy lifting, so a 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 states a specific verb ('Prepare') and a specific resource ('bounded unsigned Solana source action'), and scopes it to the legacy v1 session step. It clearly distinguishes itself from v2 siblings by naming them, so an agent can tell it apart without opening other schemas.

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

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

It explicitly states when to use it ('after assetfare_create_session and explicit caller approval') and when not to use it ('for a v2 route use assetfare_v2_prepare or assetfare_v2_session_create instead'). This is exactly the when/when-not/alternative guidance expected.

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, idempotentHint=true, and destructiveHint=false. The description adds specifics beyond annotations: it makes a network request and never authenticates, creates a session, prepares an action, signs, or submits. This aligns with annotations and provides richer 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?

Two tightly packed sentences with zero filler. The core purpose is front-loaded, and the usage guidance and behavioral disclosure follow efficiently. Every sentence 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 simple legacy quote tool with only 2 parameters, full schema coverage, and clear annotations, the description provides all necessary context: legacy status, exact corridor, and explicit routing to the v2 alternative. 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 description coverage is 100%, so both parameters are fully documented in the schema. The description itself doesn't add parameter-level details beyond the route context, which is already clear from the purpose. Baseline 3 is appropriate since 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 ('get'), resource ('Solana SOL to Base or Arbitrum ETH pricing'), and clearly identifies it as the legacy v1 original-corridor quote. It explicitly differentiates from the v2 sibling tool, making the purpose unambiguous.

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

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

Explicitly instructs when to use ('with the unversioned legacy wallet-auth/session tools') and when not to ('for every new or six-chain evaluation use assetfare_v2_quote instead'). Names the alternative directly, leaving no 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond those annotations: it 'makes a network request; never signs or submits' and states that the view selection 'never advances the workflow.' No contradiction with the annotations exists.

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 two sentences with no filler. It front-loads the primary action, then adds the key routing instruction and safety caveat. Every sentence 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 simple read-only tool with 3 fully described parameters and no side effects, the description is nearly complete. It covers purpose, usage, legacy vs v2 routing, and behavioral guarantees. It could go slightly further by describing the shape of the returned data, but the absence of an output schema is mitigated by the description stating exactly which projections can be read.

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. The description does not add much parameter-level meaning; the schema already documents view projections, the legacy session UUID, and the sensitive access token. The phrase 'current unsigned action' slightly reinforces the next_action enum, but the schema already explains this.

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 a legacy v1 session summary, workflow state, receipt, or current unsigned action.' It clearly identifies the legacy v1 scope and distinguishes it from v2 tools by naming the exact alternative (assetfare_v2_session_get).

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 ('inspect or resume a session created by assetfare_create_session'), when not to use it ('for a v2 session use assetfare_v2_session_get instead'), and what to avoid ('do not use this call to advance state'). This fully routes an agent to the correct sibling.

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 readOnlyHint=false, which could imply a mutating operation, but the description clarifies the actual scope: 'Makes a network request and creates login-challenge state, but cannot move funds, sign, or submit.' This meaningfully contextualizes the non-read-only hint and prevents the agent from assuming the tool can execute transactions. No contradiction with 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?

Three sentences with zero waste: the first fronts the core purpose with key qualifiers, the second provides usage conditions and exclusion, the third discloses behavioral limits. Every sentence earns its place and the most decision-relevant information appears first.

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 tool with no output schema, the description covers purpose, preconditions, exclusions, and behavioral safety limits comprehensively. The only minor gap is that it doesn't name the natural follow-up step (e.g., assetfare_finish_wallet_auth) or hint at the response shape, but the sibling naming and 'login-challenge state' mention make this a small omission rather than a blocking one.

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 sole parameter 'source_wallet' is already well documented in the schema as a caller-owned public address with an explicit warning against seed phrases/private keys. The tool description adds only indirect context (the fresh quote precondition), so the schema carries the heavy lifting and the 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 states a specific verb ('Create') and a specific resource ('short-lived, non-transactional Solana signMessage challenge'), scoped precisely to the legacy v1 workflow. It also distinguishes itself from the sibling family by explicitly noting that v2 quote and session tools do not use wallet authentication, 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?

The description gives explicit preconditions ('Use only after selecting a fresh legacy assetfare_quote and obtaining caller approval') and an explicit exclusion ('v2 quote and session tools do not use wallet authentication'). This tells the agent both when to invoke this tool and when not to, leaving little 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds value beyond them by disclosing 'makes a network request' (latency/connectivity implications) and 'never authenticates, signs, submits, or advances a session' — exclusions that matter given session- and auth-oriented siblings. The leading 'Read-only' slightly echoes readOnlyHint, but the rest is genuinely additive.

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 zero waste: purpose, usage routing, and behavioral caveats. The main purpose is front-loaded, and each sentence earns its place. The only redundancy is the word 'Read-only' echoing readOnlyHint, which is negligible given the new information packed into the same sentence.

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 0-parameter read-only status tool with rich annotations, this is nearly complete: purpose, workflow placement, and behavioral exclusions are all covered. The return format is not specified (no output schema exists), but the output is strongly implied by the stated purpose — compatibility status and safety gates — so this is a minor gap rather than a serious one.

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?

Tool has 0 parameters with an empty schema (additionalProperties: false), so the baseline is 4 and there is nothing for the description to document. No parameter semantics are needed or expected here.

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?

Description opens with a specific verb+resource: 'Read legacy v1 compatibility status and original-corridor safety gates.' It explicitly names what it is not by routing v2 workflows to assetfare_v2_capabilities, which distinguishes it from the closest sibling 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 positive condition ('Use only before the unversioned Solana-SOL-to-Base/Arbitrum-ETH workflow') and an explicit exclusion with the named alternative ('for every six-chain v2 route use assetfare_v2_capabilities instead'). This is textbook when/when-not guidance with a specific sibling fallback.

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 provide readOnly, idempotent, non-destructive hints. Description adds important context about continuation_v3 being restart-fail-closed and binding the full payload, which is behavioral detail not in annotations. Also clarifies no login/session creation, reinforcing safety.

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

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

Three sentences, front-loaded with the key instruction. Example is useful but slightly verbose; still efficient for the complexity. No wasted words.

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?

Tool has zero parameters and output schema exists, so return values are covered. The description explains prerequisites, safety, and how it relates to quoting. Complete for an agent to call correctly 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?

Schema has zero parameters and 100% coverage, but description adds meaning by explaining the tool's role in reading contracts. With no params, the description explains what the tool does with its environment, compensating for lack of schema 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 specific verb 'Read' + resource (multiple contracts), clearly distinguishing from siblings. It names the exact artifacts to inspect and gives a concrete example usage, making purpose unambiguous.

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

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

Explicitly says to inspect before quoting, names a specific example scenario, and states when it applies. Does not name alternatives but context signals indicate it is a prerequisite for quote tools, which is clearly implied.

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

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

Annotations already mark this as read-only and non-destructive, so the safety profile is covered. The description adds useful behavioral context beyond annotations: no network call is made, the output is a sensitive bearer capability, and it is never a private key. This is meaningful additional transparency without contradicting 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?

The description is compact and front-loaded with the most important constraint ('Local stdio only'). Each sentence adds distinct value: scope, generation mechanics, and security classification. There is no fluff or redundant restatement of the tool name.

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

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

With zero parameters and an output schema present, the description covers everything an agent needs to know: when to use it, how remote clients should behave instead, where the result should be passed, and the security sensitivity of the value. Nothing critical is missing.

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

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

The tool has zero parameters and the schema is empty, so the baseline is 4. The description compensates by clarifying the semantic nature of the generated value and how it is encoded, which is the only parameter-like information an agent needs.

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 ('generate') and a specific resource ('one caller-owned 256-bit session capability') without a network call. It also clearly distinguishes the local stdio context from remote MCP/A2A servers, so an agent can differentiate this from the many session-related 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?

The description explicitly says this helper is local stdio only and that remote clients should generate the capability themselves by producing 32 random bytes and base64url-encoding them. It also instructs that the result should be passed to assetfare_v2_session_create and every lifecycle call, giving concrete usage direction.

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 critical behavior: no field is auto-inserted, AssetFare never signs or submits, caller_approved:true is not human-proof, and multi-step quotes reject one_shot. These are exactly the non-obvious traits an agent needs to avoid unsafe or invalid calls. No contradiction with 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?

The description is compact and front-loaded with the core purpose, followed by binding mode, example, fallback, and safety warnings. Every sentence carries distinct information and none is filler. The structure moves from what it returns to how to invoke it correctly.

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 9 parameters, nested objects, and open-world hint true, the description covers the essential workflow and safety semantics: binding mode, fallback behavior, no-auto-insertion, and no signing/submission. The output schema exists and can carry return-value details, so nothing critical is missing for correct 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 coverage is 100%, so the baseline is 3, but the description adds meaningful parameter context: it links approval_v3 to server-enforced quote binding, explains that omission falls back to legacy_advisory, and clarifies caller_approved is a required explicit assertion. That raises the score above baseline without repeating 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?

The description opens with a specific verb and resource: 'Return the exact validated first unsigned bundle.' This clearly distinguishes prepare from quote and session tools: it returns a bundle, not a quote or a session handle. The word 'first' and 'unsigned' add precise scoping.

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: for server-enforced binding, pass caller_approved=true plus an approval_v3 selected as one_shot from the exact quote. It also states a when-not condition ('multi-step quotes reject one_shot') and the alternative fallback ('Omitting approval_v3 uses legacy_advisory only'). This leaves little 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?

The description goes far beyond the readOnly/destructive annotations by enumerating exactly what the adapter verifies (hashes, fingerprint, wallet/signer requirements, path, bounds, modes, TTL) and what it refuses to do (auto-select, treat caller_approved as human proof, authenticate/prepare/sign/submit). No annotation contradiction.

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?

Every sentence carries distinct information: purpose, verification behavior, non-behaviors, an example, and the read-only boundary. It is front-loaded with the core action and remains dense without fluff.

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 an output schema and rich annotations, the description covers behavior, safety, and verification comprehensively. It does not explicitly link to sibling tools (e.g., when to hand off to prepare), but the available output schema and parameter descriptions fill most remaining operational gaps.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly. The description's example ('quote solana USDC to Base USDC at USD 1000') is illustrative but adds no new parameter 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?

The verb 'Get' plus the resource 'one unranked fresh candidate' states precisely what the tool returns, and the qualifiers 'unranked', 'direct_route_summary', and 'continuation_v3' distinguish it from prepare/session siblings. The closing 'read-only; never authenticates, prepares, signs, or submits' reinforces the 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?

It gives clear context for use: request a fresh quote candidate and do not treat caller_approved as proof or auto-select. The negative statements implicitly exclude prepare/session tools, though it never names an alternative or says 'use X when you need Y'.

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?

It discloses that 'AssetFare never signs or submits', a critical safety behavior beyond the annotations' mutability and idempotency hints. It also reveals the two operational modes (server-enforced binding vs legacy_advisory) based on approval_v3 presence. It does not cover failure modes or authorization scope, but the annotations already carry the core safety profile.

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

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

The description is compact and front-loaded with the action, then gives binding-specific guidance, then a safety note. Each sentence serves a purpose; the 'Example:' phrasing is slightly informal but not 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?

For an 11-parameter tool with nested objects, the description provides key invocation directives but leaves the surrounding workflow implicit, such as how the caller obtains the approval_v3 and when to use this tool versus quote/prepare/get siblings. The output schema covers return values, so that gap is acceptable, but the process context is thin.

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 cross-parameter meaning: caller_approved, approval_v3, idempotency_key, and session_token must be coordinated for server-enforced binding. It also clarifies the effect of omitting approval_v3, which is not fully evident from 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 states a specific action, 'Create one receipt-driven workflow', and ties it to session selection for multi-step quotes, which helps distinguish it from get/observe siblings. However, 'receipt-driven workflow' is jargon and the description does not explicitly name sibling tools to reinforce differentiation.

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 concrete conditions: pass caller_approved=true, the exact approval_v3 selected as session, the same idempotency_key, and a caller-local session token for server-enforced binding. It also specifies that omitting approval_v3 uses legacy_advisory only, offering a clear alternative mode. It stops short of explicitly routing the agent to quote/prepare first or excluding sibling 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral guarantees beyond those: 'without advancing it' and 'never signs or submits,' which clarify the state effects. No contradiction with 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?

Two sentences with no filler: the first states purpose and scope, the second gives an example and reiterates read-only behavior. Every sentence 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 rich schema descriptions, full annotations, and an output schema present, the description fully covers what the tool does, when to use it, and its non-mutating behavior. Nothing essential is missing for correct 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 description coverage is 100%, with detailed parameter descriptions for session_id and session_token covering origin, usage, sensitivity, and format. The description itself adds no new parameter semantics beyond restating 'caller-owned session_token,' 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 uses a specific verb ('Read') and resource ('existing v2 workflow and current unsigned action') and immediately clarifies the non-advancing, read-only nature. This distinguishes it from action-oriented siblings like assetfare_v2_session_refresh_action and signing/submitting 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 a concrete use case ('after a restart') and states the tool does not advance, sign, or submit. It does not explicitly name alternatives or say when not to use it, but the context is clear enough for an agent to select it for inspection.

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 genuinely useful behavior beyond annotations: 'advance the workflow' clarifies this is a state-mutating step (consistent with readOnlyHint=false), while 'AssetFare observes but never signs or submits' prevents an agent from mistaking this for a transaction-submission tool. The example further discloses that transaction_hash comes from an external producer.

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

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

Three short, front-loaded elements — core action, a concrete example, and the key safety constraint — with no filler. Every sentence earns its place and the most important directive ('record output, advance workflow') appears first.

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 an output schema present, the description need not explain return values, and the annotations already cover idempotency and destructiveness. The description covers the essential call semantics (what to record, when it exists, what happens next); the only notable gap is explicit error/prerequisite context, but the 100%-coverage schema and rich annotations carry that weight.

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 even with no param detail in the description. The example (transaction_hash='<caller-or-provider-output-hash>' with idempotency_key='output-0001') adds mild connective value showing how the two optional/required params combine, but it does not materially compensate beyond the already-rich 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 verb ('Record') and resource ('already-produced bridge or destination output'), and adds the workflow-advancing consequence. It distinguishes itself from the sibling observe_source tool via the 'destination output' phrasing, but never names the sibling explicitly, leaving the contrast partly implicit.

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?

'Already-produced' implies this tool is for outputs created outside AssetFare, and 'advance the workflow' signals the follow-on effect — that is usable context. However, no sibling alternative (notably assetfare_v2_session_observe_source) is named, and there is no explicit when-not-to-use or exclusion guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the mutation and idempotency are covered. The description adds valuable behavioral context: it observes but never signs or submits, and it advances the workflow. It also warns about idempotency_key reuse semantics, which is beyond the schema. The only minor gap is not describing what the response contains, but the output schema exists and the description's behavioral notes are strong.

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 two sentences plus an example, with no wasted words. The core action is front-loaded, the example is immediately useful, and the critical warning ('Never pass an unsigned hash') is placed at the end for emphasis. Every sentence 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 mutation tool with an output schema and 100% schema coverage, the description is nearly complete. It covers the action, the example, the idempotency semantics, and the critical constraint. The only thing missing is an explicit statement of what 'advance the workflow' means in terms of state transitions, but the sibling tools and output schema likely cover that. This is a strong, complete description for the tool's 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 100%, so the schema already documents all four parameters thoroughly. The description adds value by explaining the relationship between transaction_hashes and the workflow ('already signed and submitted'), and by giving a concrete example. It also reinforces the idempotency_key semantics. This is above the baseline 3 because the description clarifies the intended usage pattern beyond the schema's 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 states a specific verb ('Record source hashes... then advance the workflow') and resource ('source hashes the caller already signed and submitted'), and it distinguishes itself from the sibling assetfare_v2_session_observe_output by focusing on source hashes and workflow advancement. The example and explicit warning ('Never pass an unsigned hash') make the tool's purpose unmistakable.

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: record already-signed source hashes and advance the workflow. It also provides a concrete example with transaction_hashes and idempotency_key, and it explicitly warns against passing unsigned hashes. The sibling context (observe_output) further clarifies the alternative, though the description itself doesn't name it; the example and warning are strong usage guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds value beyond those by gating the operation on session state (expired but unsubmitted) and by disclosing the standing guarantee that 'AssetFare never signs or submits.' No contradiction with annotations; readOnlyHint=false is consistent with a refresh mutation.

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

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

Three compact sentences, front-loaded with the core purpose, followed by a concrete example and then a safety constraint. Every sentence earns its place with zero filler or repetition of schema details.

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 an output schema exists and all three parameters are simple required strings fully documented, the description covers the one non-obvious behavioral requirement: the unsubmitted-state gate. A minor gap is the lack of error behavior when a refresh is attempted on a submitted step, but the prohibition is stated clearly enough for correct 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 description coverage is 100%, so the baseline of 3 applies; the schema already fully documents all three parameters. The example adds mild usage color ('pass the existing session_id...', idempotency_key='refresh-0001') but no substantive semantic meaning 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?

'Refresh an expired action' states a specific verb plus resource, and the qualifier 'only while it remains unsubmitted' narrows the scope precisely. The explicit 'Never refresh a submitted step' differentiates it from the session_* observation tools without needing their 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?

The description gives a clear when-condition (expired, still unsubmitted) and an explicit when-not ('Never refresh a submitted step'). However, it does not name an alternative tool to use for the submitted-step case, leaving the fallback path 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 provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it requires caller approval, makes a network request, never signs or submits, and advances a stateful workflow. This goes beyond schema/annotations without contradicting them, though it could say a bit more about failure behavior.

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

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

Three sentences, each carrying distinct value: purpose, usage/alternative, and behavioral caveat. The most important scoping information is front-loaded, and there is no repeated or filler content.

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

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

For a stateful v1 workflow step with no output schema, the description adequately covers ordering, v1/v2 routing, and safety profile. It could be slightly more explicit about what 'advances the workflow' means for subsequent steps or response interpretation, but the essential invocation context is present.

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 each parameter has a clear, detailed description (e.g., signature format and security warning, session_id scope, access_token sensitivity, idempotency_key reuse rule). The tool description itself adds workflow context but does not need to repeat parameter details; the 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 uses a specific verb ('Verify'), names the exact resource ('finalized Solana source signature already submitted by the caller'), and states the workflow effect ('advance the legacy v1 workflow'). It also explicitly distinguishes this tool from the v2 sibling assetfare_v2_session_observe_source, so an agent can select it 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?

The description gives an explicit precondition: use only after the caller independently submits assetfare_prepare_source_action. It also states the alternative for v2 sessions, making the when-to-use and when-not-to-use boundaries clear. The added note about caller approval and network behavior further clarifies prerequisites.

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