mcp-server

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

Goes far beyond the annotations: discloses the inline Verify Wallet widget, the consent prompt and cancelled-call behavior, stale tool output after widget use, zero-balance stealth-address caveats, shielded Zcash rejection (shielded_zcash), unsupported legacy BNB addresses, and that ETC counts for proof of funds but is not a settlement asset.

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 and the sections are topically organized, but the description is very long for a one-parameter tool and contains repetitive chain guidance (EVM coverage, Zcash rules) plus prompt-like all-caps instructions that could be trimmed. Much of it earns its place operationally, but it is not concise.

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 open-world multi-chain scope, consent widget, and verification handoff, the description supplies everything an agent needs: return widget behavior, post-verification re-check instructions, custody fallback, and chain-specific caveats. The output schema covers return values, and the description still explains the user-facing rendering appropriately.

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?

Although the schema already documents the single address parameter at 100% coverage, the description adds substantial meaning: EVM 0x addresses work across multiple chains, Zcash requires t1/t3 transparent addresses, Dogecoin D… vs 9…/A… multisig behavior differs, and bnb1 legacy addresses are unsupported.

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

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

States a specific verb and resource (submit a public crypto wallet address) and the business purpose (verify ownership and count holdings toward a Proof of Funds letter). It distinguishes itself from siblings like get_wallet_summary, verify_wallet_signature, and verify_wallet_transfer by explaining it creates the verification challenge those tools consume.

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 covers when to use it (new wallet, retry after FAILED/unverified, re-call when already verified), when not to force it (exchange custody), and what to do after widget verification (call get_wallet_summary first). It also gives chain-specific preconditions, such as asking Zcash users about transparent addresses before starting.

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 readOnly or idempotent annotations, it explicitly says it does not move, sell, convert, or reserve crypto, that unverified wallets never count, and that the result is a coverage estimate rather than a loan decision. It also says the response lists which requirements are still incomplete, which the annotations do not reveal.

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

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

The core comparison is front-loaded, followed by what the check returns and the usage examples. It is dense but almost every clause adds either scope, a usage trigger, or a safety boundary; the caveat sentences could be tightened slightly.

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

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

The description covers the input intent, the verification prerequisite, the kinds of gaps the response reports, and the read-only safety profile, while an output schema already documents the return values. Nothing an agent needs in order to call this tool 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 already fully documented, including the omit-to-use-saved-price behavior. The description confirms that asset narrows the check to one asset and that the target amount is compared against verified buying power, but adds little beyond the schema apart from intent.

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 compares target_price_usd against verified buying power and reports remaining gaps (identity check, wallet verification, shortfall). It also separates itself from generate_proof_of_funds by positioning this check as the step before that letter is produced.

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 concrete triggers — the "can my Bitcoin cover a $2 million home?" question and pre-Proof-of-Funds checks — and notes that the wallet must be verified. It never names an explicit alternative to use instead (for example, the UI-oriented open_buying_power_panel or generate_proof_of_funds itself), so the routing guidance stops short of full coverage.

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

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

Goes well beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by clarifying the tool creates a letter only and does not move, convert, or reserve funds, that the download link is valid for 30 days, that an inline widget renders, and that cancelled/failed calls should be retried rather than reported as success. The ceiling-rejection behavior and the warning against using total_verified_usd are exactly the non-obvious traits 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?

Purpose is front-loaded and the ALL-CAPS section labels (CANCELLED-CALL HANDLING, CEILING) make the critical operational guidance scannable. It is longer than ideal — the widget/download-URL passage and the financed-offer aside could be trimmed — but nearly every sentence carries distinct information.

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

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

An output schema exists and the description still names the key return value (download_url), which is what the agent must check before telling the user the POF was generated. With prerequisites, ceiling rule, fund-safety disclosure, and retry semantics all covered, nothing an agent needs to invoke or report this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by giving real semantic constraints on amount: it must be ≤ pof_ceiling_usd from get_wallet_summary, and it explains why total_verified_usd is not a valid ceiling because it is pre-haircut. Currency is left to the schema, which handles it adequately via the enum.

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+artifact: generate a crypto Proof of Funds letter PDF for the authenticated user, with a clear explanation of what the document is and what it omits (no crypto references). This is unmistakably distinct from siblings like get_wallet_summary or generate_realscore_report.

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 frames when this applies (cash offer on real estate, optional on financed offers) and states prerequisites: completed identity verification and at least one verified wallet. It also routes to get_wallet_summary when the ceiling is unknown, which is a concrete alternative-call instruction.

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

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

Goes well beyond the annotations: states preconditions and that it reports what is missing, discloses the 30-day private download link, explains that each call regenerates at current values while a repeat within minutes returns the same report (matching idempotentHint=true), and draws explicit scope boundaries (not a loan decision/pre-approval, does not move, convert, or reserve crypto). This is the kind of operational and safety context annotations cannot carry.

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

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

Front-loads what the report is, then prerequisites, then return behavior, then limits — a sensible information hierarchy. The prose is dense with no filler sentences, though it is on the longer side for a no-parameter call.

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?

An output schema exists and the description still covers preconditions, regeneration/idempotency nuance, link lifetime, and explicit non-goals. Nothing an agent needs to decide whether and how to call this 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description adds no parameter discussion, which is appropriate since there is nothing to document and the schema is empty.

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

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

States a specific verb and resource ('Creates the user's RealScore Report') and then defines precisely what the artifact is and contains (identity, verified wallets, holdings, balance history, conversion adjustment). An agent can tell what it produces without opening the schema. It never names the closest sibling, generate_proof_of_funds, so explicit sibling differentiation is missing.

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 clear triggering context ('the asset verification document a buyer gives a mortgage lender when the down payment or reserves come from crypto') plus hard prerequisites (verified identity, at least one verified wallet). What is absent is any when-to-use-this-vs-that guidance relative to generate_proof_of_funds or the other wallet/verification 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the response includes activation.next_action and renders an inline progress widget, with an instruction to keep accompanying text short. A small deduction only because it doesn't mention cost/latency or auth prerequisites, which is minor for a no-arg status read.

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

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

Front-loads purpose, then exclusion-and-alternative, then trigger conditions, then return/presentation details. Though longer than one line, every sentence carries distinct operational information (scope, routing, next_action, widget handling) with no filler.

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

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

An output schema exists, so return values need not be fully spelled out, and the description still highlights the single critical field (activation.next_action). Combined with annotations and zero params, an agent has everything needed to call it correctly and interpret the result.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly implies a no-input status check.

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 (returns) and resource (high-level account overview) and enumerates the three things included: identity verification state, wallet count, and Proof of Funds eligibility. It explicitly carves out wallet-specific scope versus get_wallet_summary, so an agent can distinguish it from siblings 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 both directions explicitly: DO NOT call it for wallet summaries/lists/balances and use get_wallet_summary instead, plus the positive trigger ('is my account ready?', resuming setup). The named alternative and the condition that selects it are unambiguous.

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

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

Goes well beyond the read-only/idempotent annotations: it discloses the result cap ('up to 20 matching entries'), the no-match fallback (returns available categories), and detailed next-action metadata semantics including sequencing rules ('never lead with the offer', 'never repeat it after a decline'). This is behavior an agent could not infer from the schema or 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 purpose and fallback behavior are front-loaded, but the opening sentence is a sprawling example list that could be trimmed, and the next-action metadata passage runs long with repeated prohibitions. Content is mostly justified, yet the density-per-idea is low.

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 and annotations covering safety, the description fills the remaining gaps: result limit, empty-result behavior, and how to act on next-action metadata. Minor omission: it never states whether search is exact or fuzzy, though that is a small residual gap.

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

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

Schema coverage is 100% and both parameters are documented there, including category examples. The description only restates 'by keyword and/or category,' which conveys optionality that the schema's empty required list already establishes, so it adds little beyond structured data.

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

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

States a specific verb and resource ('Search RealOpen's frequently asked questions... by keyword and/or category') with concrete topical scope. It is clearly distinguishable from siblings like get_how_it_works, get_fee_structure, and get_snippets, which cover structured product info rather than free-text FAQ retrieval.

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

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

Gives an explicit trigger ('when a user asks a specific question about the process') and enumerates the kinds of questions that qualify, plus 'prefer this over guessing from general knowledge.' It stops short of naming which sibling tool to use instead when the question is not an FAQ question (e.g. get_fee_structure for fee tables), so routing is clear 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 this is read-only, idempotent, and non-destructive. The description adds real context beyond them: it reflects a live fee schedule, supersedes stale model estimates, includes worked examples, and can return recommended_next_action fields along with strict rules for acting on 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 purpose is front-loaded and the first two sentences earn their place. However, the NEXT-ACTION METADATA block is long, procedural, and disproportionately verbose relative to a zero-argument lookup tool, burying the core value proposition.

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?

An output schema exists, so return values need not be explained, and the description correctly flags the recommended_next_action field. For a no-parameter read tool this is essentially complete, with only minor excess in the conversational follow-up policy.

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

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

The tool takes zero parameters and the schema is fully covered, so there is nothing parameter-level to disambiguate. The description correctly implies the call is context-free and needs no arguments.

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

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

The opening sentence gives a specific verb and resource: 'Return RealOpen's current pricing and fee breakdown for buying real estate with crypto, with worked examples.' That clearly separates it from informational siblings like get_how_it_works, get_faq, and get_snippets.

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

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

Explicit trigger conditions are given ('whenever a user asks what it costs to buy a house with Bitcoin... fees, commissions, or total out-of-pocket'), plus a strong reason to prefer it over model knowledge. It doesn't name a specific alternative sibling for related pricing questions, so it stops short of a full when/when-not map.

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 readOnly/idempotent/non-destructive annotations, the description explains that the content is RealOpen-maintained and more current than model knowledge, that conversion/funding/closing happen outside the chat, and that the tool only explains the process. It also discloses recommended_next_action behavior and how to handle possible purchase intent, which is substantial context not present in the structured 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 purpose is front-loaded, but the description is very long and includes extensive next-action sales guidance that is not needed for selecting or invoking the tool. Much of the latter half does not earn its place in a tool definition.

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 tool has an output schema, full schema description coverage, and clear annotations. The description provides enough scope, usage context, and behavioral boundaries 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%, so the single perspective parameter and its enum are already fully documented. The description repeats the perspective meanings and confirms filtering, but adds little semantic value 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 description states a specific verb and resource: explaining RealOpen's end-to-end crypto real-estate purchase flow, from verified holdings through offer and closing. It is clear about what the tool does, but it does not explicitly name or differentiate itself from close siblings such as get_faq or get_snippets.

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 concrete example user questions and says to use it for questions about RealOpen's process, timing, or end-to-end flow, with perspective filtering. It provides strong usage context, but does not explicitly say when another sibling tool should be used instead.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious context: the ref_id is resolved server-side from the affiliate/agent record and must not be requested from the user, and the returned URL must be appended for click attribution. It doesn't discuss failure behavior when no affiliate record exists, which would have made it 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?

Three tight sentences: what it does, when to use it, and the key implementation caveat. Nothing is redundant and the most decision-relevant information (the action) 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?

With an output schema present, return values need not be explained, and the description covers purpose, usage, and the ref_id resolution behavior. The only omission is what happens when the user has no affiliate record, which leaves a small edge-case gap.

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

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

Schema coverage is 100% and the single 'path' parameter is documented with examples and a default, so the description adds little parameter detail beyond the domain hint 'realopen.com page.' Baseline 3 is appropriate when the schema carries the 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?

States a specific verb and resource — 'Construct a tracked referral URL' pointing at a realopen.com page — which is unambiguous and clearly distinct from every sibling tool listed (wallet, status, and content tools). An agent knows exactly what artifact this produces.

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

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

Gives an explicit trigger set: 'whenever you produce marketing content, recommendations, or sign-up suggestions.' That is strong positive guidance. It stops short of naming when-not-to-use cases or alternatives, but no sibling overlaps this function, so the gap is minor.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely non-obvious behavior: the response carries recommended_next_action metadata tied to purchase intent, and there are stated rules for surfacing it (answer first, one short sentence, never paste verbatim, never repeat after a decline). This is exactly the kind of context structured fields cannot carry.

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

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

The factual purpose is front-loaded in the first sentence and the follow-up policy is explicitly delimited with a 'NEXT-ACTION METADATA' marker. It is on the long side for a zero-argument lookup — the next-action block occupies roughly two-thirds of the text — but each constraint (don't lead with the offer, don't repeat after a decline) is operative rather than 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?

An output schema exists, so return values need not be spelled out, and the annotations carry the safety profile. The description still covers what the tool answers, when to reach for it, and how to act on its metadata, leaving no material gap for an agent calling a no-input lookup.

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

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

Zero-parameter tool, so the baseline is 4. The description correctly implies no input is needed by framing the tool as a coverage lookup, and there are no parameters whose meaning needs elaboration.

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

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

States a specific verb and resource ('Return where a buyer can currently use crypto to buy real estate') and enumerates the three content dimensions: geographic coverage, supported property types, international availability. This clearly separates it from siblings like get_supported_crypto (which cryptos, not where) and search_assets.

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

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

Explicit triggering conditions are given ('use this whenever a user asks whether they can buy a house with crypto in a particular state or country, or whether RealOpen supports a property type'), plus detailed exclusion criteria for the follow-up offer (not an agent/escrow/title professional, not idle research, not already declined). It stops short of naming a sibling alternative for overlapping questions, but the when-to-use context is otherwise concrete.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that snippets are pre-approved by marketing and lists the returned fields including body text, tags, share title, and asset preview, which helps set expectations 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 four sentences and front-loads the core definition before usage and filter details. The final sentence overlaps with the output schema's coverage of return fields, but it remains short and readable.

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 rich annotations, a full input schema, and an output schema, the description covers purpose, when to use, filterable dimensions, and return contents. It does not spell out pagination or how multiple filters combine, which are minor gaps for a read-only snippet lookup.

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 description coverage, the schema already defines each of the five optional filters, including enum values and the tags 'matches ANY' behavior. The description repeats the filter dimensions but adds no syntax, default, or combination 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 description opens with a specific verb ('Find') and a precisely scoped resource ('pre-approved RealOpen social-media snippets'), then enumerates platform contexts. It clearly distinguishes this lookup from sibling tools like search_assets by focusing on marketing snippet content rather than asset records.

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 usage trigger: 'Use this when a user asks for ready-to-post content or needs inspiration grounded in approved brand voice.' It does not name a 'do not use' case or point to an alternative tool, but the scenario 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context — and it does: it discloses that the response renders an inline Get Started widget, that the primary CTA is state-aware, that activation.next_action dictates the correct follow-up tool, and critically that 'nothing here moves funds' (conversion/funding/closing happen outside chat). That last point is a real behavioral boundary an agent could not infer from 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?

Front-loaded correctly — the opening sentence establishes what it is and who it's for before any routing rules. It is dense though: a single long paragraph packing triggers, exclusions, widget behavior, and next_action handling would scan faster as a structured list, and the closing sentence ('never make the user figure out which step comes next') slightly restates the activation.next_action point.

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 zero-parameter, read-only routing/discovery tool with an output schema and full annotation coverage, the description supplies everything an agent needs: entry conditions, exclusions, what the response contains, that a widget handles presentation, how to consume the structured next_action, and the assurance that no funds move. Nothing material is missing.

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

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

Zero parameters, so there is nothing for the description to disambiguate and the dimension defaults to the 4 baseline. The description does not need to compensate for anything, but it also earns no bonus for parameter guidance.

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

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

Opens with a specific framing ('The front door to buying real estate with crypto through RealOpen') and states precisely what it returns: 'the setup path from a fresh account to a Proof of Funds letter', plus state-aware next-step resolution for signed-in users. This is distinct from the sibling knowledge tools (get_faq, get_how_it_works, get_fee_structure) and from action tools like start_identity_verification or generate_proof_of_funds.

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

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

Explicit when-to-call triggers are enumerated (new user, no specific request, buying-intent signal, offer-ready/proof-of-funds questions), and there is an explicit when-NOT clause: 'Do NOT call it after every general educational question — for pure product questions ... answer with the dedicated knowledge tools'. It even names the alternative category, which is exactly what separates this from get_faq/get_how_it_works.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world status, so the bar is lower. The description earnably adds that the data is RealOpen-maintained and should override possibly-stale model knowledge, and it discloses that responses may carry recommended_next_action metadata with rules for surfacing it. It does not address freshness/caching or response shape, keeping it at 4.

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 factual core is front-loaded in one tight sentence, which is excellent. However, the NEXT-ACTION METADATA block is roughly half the total length and encodes conversational sales policy (don't lead with the offer, don't repeat after a decline) that is verbose for what it adds.

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 and no parameters, the description needn't explain return values, and it covers the essential trust caveat about staleness. The only remaining gap is freshness guarantees for a list explicitly advertised as 'live'/'current', which an agent might reasonably want.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly avoids inventing filtering options that the schema does not expose.

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 first sentence names a specific verb ('Return') and precise resource ('current list of cryptocurrencies, blockchains, and stablecoins a buyer can use'), including concrete examples (BTC, ETH, USDC, USDT). This is clearly distinguishable from siblings like search_assets or get_fee_structure.

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

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

Explicit trigger contexts are given ('can I buy a house with X?', 'can I pay for property with X?', 'whenever a user needs the live list'), which is strong routing guidance. It stops short of stating when NOT to use it or naming a specific sibling alternative for overlapping questions, so it falls just below 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: it renders an inline widget and the agent should only summarize counts, it distinguishes three USD figures with the haircut and exclusion rules, and it flags ETC as counted-but-not-settleable. Edge-case semantics (zero_balance_hint, full_wallet_hint, transparent_only_hint, staking transferable:false) are all disclosed.

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

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

Front-loaded with the trigger sentence and the widget/presentation rule, then organized under scannable caps-labeled blocks (THREE NUMBERS, ETHEREUM CLASSIC, PRESENTATION, STAKING). It is long and dense for a zero-parameter read tool, with some rules that arguably belong in sibling tool descriptions, but nearly every sentence prevents a concrete misuse.

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 the tool's high domain complexity, an output schema, and downstream workflows (POF letters, verification, unstaking), the description equips an agent to call it and interpret the result correctly. The three-number disambiguation and the hint-passthrough rules close the gaps that would otherwise cause wrong POF amounts or wrong wallet identification.

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

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

The tool takes zero parameters and the schema has 100% description coverage, so there is nothing for the description to disambiguate at the input layer — the baseline of 4 applies. The description's parameter-adjacent guidance is about output fields and downstream tool arguments (wallet_id used only as a parameter for other tools), not inputs 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?

States a specific verb and resource ('get_wallet_summary' → return all wallets for the authenticated user with balances, verification status, and POF ceiling) and enumerates the user phrasings that map to it. It is clearly separable from siblings like generate_proof_of_funds, refresh_wallet_balance, and link_wallet_xpub, which are named as follow-on 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?

Explicit when-to-use triggers are given ('whenever the user asks for a wallet summary, wallet list, their wallets, wallet balances, verified holdings, or Proof of Funds ceiling'), plus routing rules to other tools (offer link_wallet_xpub for low BTC/ZEC/DOGE, suggest generate_proof_of_funds amounts at or below pof_ceiling_usd). It also states a when-not: never offer total_verified_usd or the all-wallets sum as a POF amount.

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 annotations, the description discloses verified vs pending binding behavior, automatic activation after verification, what happens on binding failure, that future refreshes rescan automatically, and that unlink reverts balance to the verified address. It also includes strong safety guidance about never accepting private keys or seed phrases and explains the privacy tradeoff of sharing an xpub.

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 scope, purpose, and usage triggers before moving into wallet-specific export instructions and safety notes. It is long but information-dense; a minor trim of wallet-by-wallet export details could improve it, but little is wasted.

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

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

For a complex, stateful wallet-linking tool, the description covers the full operational picture: supported coins, verified and pending states, multisig handling, unlink behavior, safety constraints, and user-facing export locations. An output schema exists, so return-value details are appropriately left to it.

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

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

Schema description coverage is 100%, so the schema already documents xpub formats, multisig descriptors, unlink behavior, and wallet_id. The description adds useful context about pending vs verified wallet states, but most parameter-specific meaning is already present in the schema, making 3 the appropriate 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: link or remove the extended PUBLIC key of a verified Bitcoin, Zcash, or Dogecoin wallet. It clearly distinguishes this from adding a single wallet address by explaining that every receive/change address in the account counts toward balance and Proof of Funds.

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

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

It gives explicit triggers: use when a verified BTC wallet shows less than expected, when get_wallet_summary or refresh_wallet_balance returns full_wallet_hint, when the user mentions a hardware or HD wallet, and right after add_wallet for relevant users. It also names alternatives and special cases, including unlink and multisig descriptor handling.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the OAuth token revocation, which implies subsequent calls will fail until re-authentication - a consequence the agent would not infer from the hints alone.

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, no filler, with the action front-loaded and the usage condition following. Every clause carries information.

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

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

With no parameters, full schema coverage, annotations covering the safety profile, and an output schema handling return values, the description contains everything an agent needs to select and invoke 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly avoids inventing any parameter discussion.

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

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

States a specific verb and resource: signs out of the RealOpen MCP session and revokes the OAuth token. No sibling tool performs session teardown, so it is clearly distinguishable from the wallet, status, and informational 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?

Explicitly says to use it when the user wants to switch accounts or disconnect, giving clear triggering conditions. It does not name an alternative path or state when not to use it, which keeps it just 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, yet the description still adds real value: the verification mechanics (public address with signed message or dust transfer, xpub linking), the hard security constraint 'Never ask for a private key or seed phrase', and what happens when blocked_request is set. The closing 'Read-only: it does not move, sell, convert, or hold crypto' partly restates the annotations, which keeps it just short of 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?

Front-loaded with the core action and the sibling disambiguation, then layered with workflow and safety guidance in a logical order. The opening sentence is dense with a long enumeration, and the final read-only sentence is largely redundant with the annotations, so it is efficient but not airtight.

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?

An output schema exists, so return values need not be described, and the annotations plus description cover safety, workflows, and the security constraint well. The gap is that the realscore_report workflow option is left unexplained even though the sibling generate_realscore_report exists, leaving one enum path unmapped.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining intent for the key params — 'Pass what the conversation has established (target_price_usd, asset, workflow)' and the precise conversational trigger for blocked_request. The only soft spot is that the schema's fourth workflow enum value (realscore_report) is never mentioned in either the description or the schema's own workflow text.

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

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

States a concrete verb and resource ('Opens the RealOpen panel beside the current conversation') and immediately disambiguates from the sibling open_realopen by naming it and the difference (panel vs. full-screen sidebar app). It also enumerates what the panel shows, so an agent knows exactly what content this call surfaces.

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

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

Gives explicit routing rules: use open_realopen for the full-screen app, use workflow "verify_wallet" to guide wallet verification, and set blocked_request when the user asks to transfer, send, sell, trade, convert, or hold crypto. The trigger conditions and the alternative tool are both spelled out rather than 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds real value beyond that by stating what is displayed and the privacy trait 'verified wallets (summarized, never full addresses)' plus an explicit no-custody statement. It does not address auth/connection prerequisites or any latency/refresh behavior, so it falls short of 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?

Three sentences, front-loaded with the action and trigger before the detail dump. Every sentence carries information, though the final no-crypto disclaimer is slightly verbose for a read-only viewer.

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, return values need not be spelled out, and annotations carry the safety profile; the description still covers purpose, contents, triggers, and the no-custody boundary. The only gap is the undocumented workflow parameter, which would let an agent route directly into a sub-workflow instead of the home view.

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

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

Schema description coverage is 100% and the single optional enum parameter is documented in the schema, so the baseline of 3 applies. The description never mentions the 'workflow' parameter or that it can jump straight into buying_power, verify_wallet, or proof_of_funds, missing an opportunity to explain the enum's effect.

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?

Names a specific verb and resource ('Opens the RealOpen home, the full-screen app in the ChatGPT sidebar') and immediately enumerates what the surface shows, so an agent can distinguish the overview from action tools like check_buying_power or generate_proof_of_funds. It stops short of naming the nearest sibling (open_buying_power_panel) or clarifying the overlap with the workflow parameter.

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

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

Gives explicit invocation triggers: 'when the user asks to open RealOpen, open the RealOpen app or sidebar, or see an overview of where they stand.' It also draws a boundary with 'purchase funding is coordinated on RealOpen outside ChatGPT,' which tells the agent this is not a transaction entry point. No explicit when-not-to-use vs. the workflow siblings, though.

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 say non-read-only, idempotent, non-destructive, open-world; the description adds the real behavioral traits: the empty-fetch safeguard that preserves stored balances and returns status=no_change, plus conditional response branches (zero_balance_hint, xpub_linked/full_wallet_hint, transparent_only_hint, staking_hint). Idempotency and non-destructiveness are consistently reinforced by the 'no_change keeps the previously stored composition' statement.

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

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

Purpose and trigger are front-loaded, which is good, but the bulk is a stacked run of ALL-CAPS response-handling notes (ZERO-BALANCE, BITCOIN FULL-WALLET, ZCASH, STAKING) that partly duplicate what an output schema already conveys. Roughly a third of the text could move to output-schema documentation without losing agent-critical guidance.

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

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

For a write-back refresh tool with an output schema present, the description covers everything an agent needs to call and then interpret it: the safeguard, linked_addresses, the zero-balance false-negative trap, xpub/full-wallet handling, shielded ZEC, and staking vs. liquid value. Nothing operationally material is missing.

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

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

Single parameter with 100% schema coverage; the schema already explains that wallet_id is an internal UUID from get_wallet_summary/add_wallet that must not be shown to the user. The description adds no further parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Re-fetch on-chain asset balances for an existing wallet and update the stored record.' It also scopes the business meaning (balances feed the Proof of Funds ceiling), which separates it from get_wallet_summary (read) and refresh_wallet_verification (verification state).

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

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

'Use when the user says their balance looks stale, wrong, or zero after a recent on-chain change' gives a concrete trigger condition. It also routes follow-on cases to siblings (link_wallet_xpub, test-transfer verification), though it never explicitly contrasts with the plain read path (get_wallet_summary) or refresh_wallet_verification.

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 the response renders an inline Verify Wallet widget, that the user clicks through the widget rather than the agent reading values aloud, and that internal verify_wallet_signature / verify_wallet_transfer calls may silently fail to produce a visible follow-up. It also warns that prior tool output becomes stale once the widget is used, which is critical behavioral context for a non-idempotent mutation 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 description is front-loaded with purpose and usage, then moves through return shape, widget behavior, and the post-verify re-check. It is somewhat long for a one-parameter tool, but each paragraph addresses a distinct operational concern; minor parenthetical detail keeps it from a 5.

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?

It covers the return shape, the inline widget behavior, the internal verification calls, the stale-output warning, and the required follow-up call to get_wallet_summary. With an output schema and annotations present, this is complete enough for an agent to invoke and follow up correctly.

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

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

Schema coverage is 100%, and the schema already documents wallet_id as an internal UUID from add_wallet or get_wallet_summary that should not be shown to the user. The description adds the 'existing unverified wallet' context but does not add parameter-specific syntax or lookup guidance beyond the schema, so 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 states a specific verb and resource: 'Regenerate verification challenges for an existing unverified wallet.' It distinguishes this from add_wallet by scoping it to existing unverified wallets and from verification execution tools by explaining that it produces challenges rather than verifying them.

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

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

It gives explicit triggers: a failed prior verification attempt, a user needing a fresh message to sign, or a new transfer challenge. It also provides a firm post-verification rule to call get_wallet_summary first rather than relying on stale tool output.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds critical specifics beyond them: the wallet record, verification status, and balance history are deleted, and removing a verified wallet reduces the Proof of Funds ceiling. It also gives the important UX constraint never to expose the wallet_id UUID.

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

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

Front-loaded with the destructive action and its consequences, followed by the confirmation requirement and a concrete confirmation example. Every sentence earns its place for a destructive operation.

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 and rich annotations, the description still provides everything needed for safe invocation: what is destroyed, how to confirm with the user, what not to expose, and the downstream Proof of Funds impact.

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 wallet_id parameter is already documented. The description adds procedural meaning by emphasizing that the wallet_id must be looked up internally and that confirmation must be phrased using the wallet address and blockchain, not the UUID.

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

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

States a specific verb and resource: permanently remove a wallet from the authenticated user's account. It is clearly distinct from add_wallet and other wallet-related siblings without needing to open 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?

Provides explicit pre-call protocol: confirm with the user which wallet by address and obtain explicit confirmation. It does not name sibling alternatives, but the when-to-use context and confirmation requirement are clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description earns credit by explaining why: it "may replace or clear prior planning details." The long negative inventory (no wallet/identity/document/fund/offer changes, no crypto movement, no Proof of Funds letter) adds genuine safety context an agent cannot infer from annotations alone, though it says nothing about the returned confirmation.

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

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

Purpose and trigger come first, followed by clearing semantics, then the scope limits. The final exclusion sentence is long and enumerative but each clause blocks a plausible misread (e.g., assuming it moves crypto or issues a Proof of Funds letter), so it earns most of its length.

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?

An output schema exists and annotations cover safety/idempotency, so the description only needs scope, triggers, and clearing behavior — all of which are present. Nothing an agent needs in order to call this correctly (including how to reset state) 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 all four parameters (asset, workflow, wallet_id, target_price_usd) are already documented, including null-clears semantics. The description reinforces the same set but adds no format, validation, or workflow-value detail beyond the schema; baseline 3 applies when the schema does the heavy lifting.

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

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

Names a specific verb (saves) and a specific resource (in-progress purchase planning details), then enumerates exactly which values are persisted: property price, crypto asset/wallet, and chosen workflow. It also carves out clear boundaries against siblings like add_wallet, generate_proof_of_funds, and offer/funds operations, so an agent can distinguish it without opening any schema.

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

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

"Call it when the user states or changes any of these" gives an explicit trigger, and "Pass null to clear a saved planning value" covers the clearing case. The exclusion list (does not change wallets, identities, offers, etc.) effectively rules out misuse, but no sibling is named as the alternative to use instead, which keeps it 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?

Annotations already establish that this is read-only, idempotent, closed-world, and non-destructive. The description adds useful behavioral detail beyond those annotations: results are capped at 20 assets and include URLs, captions, tags, and inline thumbnail previews for the first five.

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 tightly written sentences. It front-loads the tool's purpose, then usage context, then return behavior, with no redundant or wasted language.

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 read-only search tool with four optional well-documented parameters and an output schema, the description is complete. It covers purpose, when to invoke it, filters, result cap, and response contents.

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

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

Schema description coverage is 100%, and the schema already documents all four parameters with enum values and filtering semantics. The description restates the available filter dimensions but does not add meaningful syntax or behavioral details 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 description states a specific verb and resource: searching RealOpen's approved affiliate marketing asset library, with concrete asset examples. It is clearly distinguishable from all sibling tools, which focus on wallets, account status, FAQs, and verification rather than marketing assets.

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: use when a user asks for existing RealOpen marketing material they can download or share. It also names the supported filtering dimensions, though it does not explicitly state when not to use the tool or compare it to alternatives.

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

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

Beyond the annotations, the description discloses that this creates a new session when a prior one is incomplete, denied, or expired, and that it returns a secure hosted verification URL for the user's browser. It also adds important privacy guidance not to collect sensitive identity details in chat, though it does not cover rate limits or permission 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?

The description is front-loaded with the core action and business purpose, then adds restart conditions and the return/usage constraint. It is three sentences with no wasted text and every clause adds useful context.

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 output schema exists, the description need not explain return values in detail, yet it still mentions the hosted verification URL. Combined with annotations covering safety and idempotency, and the schema covering the force_new parameter, the description is complete 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 single parameter force_new is already fully documented. The description indirectly references restart behavior but does not add syntax or conditional details beyond what the schema already provides, making baseline 3 appropriate.

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

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

The description names a specific verb and resource: start or restart identity verification (KYC). It also clarifies the business context as the first setup step before issuing a crypto Proof of Funds letter, which distinguishes it from downstream sibling tools like generate_proof_of_funds.

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 states the primary usage context: the first setup step before RealOpen can issue a crypto Proof of Funds letter. It also explains that incomplete, denied, or expired sessions are replaced, but it does not explicitly name alternative tools or state when not to use this tool beyond the privacy warning about chat.

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

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

Annotations cover the safety profile (not read-only, open-world, non-idempotent, not destructive), so the description's added context is what counts: it discloses the prerequisite that the signature must be over the exact message from add_wallet, and that verification gates whether the balance counts toward Proof of Funds. It does not say what happens on a bad signature or whether resubmission is allowed, leaving a gap for a non-idempotent write.

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

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

Front-loads purpose, then prerequisites, then the branching procedure — a sensible order. It is on the long side and the closing admonition about not replying 'I'd need to work out the wallet_id' reads as a workaround for a prior failure mode rather than general guidance.

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, return values needn't be explained; the description covers the prerequisite, the two invocation paths, and ID sourcing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description goes further by giving operational semantics for wallet_id (look it up from the user's stated chain/address via get_wallet_summary, never show or ask for it) and by telling the agent to remind the user to paste the full signature hash.

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 concrete verb+resource ('Submit a signed message to prove ownership of a crypto wallet') and situates it in the larger workflow (counts toward a crypto Proof of Funds letter). It implicitly distinguishes itself from add_wallet and verify_wallet_transfer by naming the prerequisite message from add_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?

Explicitly branches on context: if a Verify Wallet widget is visible, the widget itself calls this tool; if not, call get_wallet_summary first then call this tool directly. Prerequisites and the alternative path are both named, with nothing left to inference.

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

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

Adds a lot beyond the annotations: it clarifies the tool does not move funds (reconciling the non-destructive intent), discloses that it performs an on-chain lookup (consistent with openWorldHint), explains auto-matching across all accepted assets, and documents the specific failure mode invalid_transaction_hash_format plus the instruction to relay assistant_guidance. Minor gap: it doesn't say whether a failed verification is retryable or whether a successful verification is final/one-shot despite idempotentHint=false.

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

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

Front-loaded with purpose and organized with clear uppercase section headers (HASH FORMAT, ASSET DETECTION, WHEN THE USER PROVIDES A TX HASH), so an agent can scan to the relevant block. It is long and carries some redundancy — the 'not a payment / does not move funds' point is restated, and the closing 'Do NOT respond with...' sentence is a defensive aside rather than tool semantics.

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 3-parameter verification tool with full schema coverage, annotations, and an output schema, the description covers everything an agent needs: prerequisites, wallet_id acquisition path, hash formats, error handling, and asset-matching behavior. Return-value details are correctly left to the 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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: asset_symbol is an audit hint that does not affect matching and should usually be omitted, and transaction_hash accepts block-explorer URLs as well as raw hashes. The concrete hash format rules (64 hex, 0x-prefixed, ~88-char Base58) and the exchange-reference-ID failure mode are substantive additions the schema does not carry.

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

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

States a specific verb and resource (submit a tx hash for the dust/test transfer verification) and immediately distinguishes it from the sibling verify_wallet_signature by framing it as 'the other way to prove ownership of a crypto wallet.' It also names the downstream purpose (balance counting toward a Proof of Funds letter) so the agent understands why it exists.

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

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

Gives explicit routing logic: if a Verify Wallet widget is visible, hand the hash to the widget rather than calling the tool; if not, call get_wallet_summary first to resolve wallet_id, then call this tool. It also states the prerequisite (user must have already sent a transfer to the deposit address from add_wallet) and names the alternative verification path.

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