FlatCash — Native Currency for AI Agents

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

Annotations are minimal (readOnlyHint: false, destructiveHint: false). The description adds valuable context by disclosing that the password action returns an API key with full permissions and that success returns scopes and account info. No contradictions 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 two sentences, starts with purpose, then breaks down actions and results. Every word earns its place with no 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 no output schema, the description mentions return values (scopes and account info), and the 4-parameter schema is fully covered. For an auth tool of this complexity, it is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the relationship between the action parameter and which other parameters are required, as well as the expected result for each action, which goes beyond the schema's individual 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 explicitly states the tool authenticates an existing FlatID user and enumerates two distinct actions (password, token) with clear outcomes. This clearly distinguishes it from sibling tools like flat_register or flat_verify.

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

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

The description provides clear context for when to use each action (password for login, token for verification) and what each requires. However, it doesn't explicitly exclude alternatives or name sibling tools, so a small gap remains.

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 key behavioral traits: escrow locking at oracle price × (1+premium%), 4-hour auto-release, zero take-rate, and permissionless operation. These go beyond the minimal annotations (readOnlyHint:false, openWorldHint:true, destructiveHint:false) and give the agent a strong sense of the trustless protocol. It stops short of describing edge cases like dispute resolution outcomes, but overall is quite transparent.

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

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

The description is long but dense; it packs the entire lifecycle, escrow mechanics, and an enumeration of all 12 actions into a compact paragraph. Every sentence earns its place, though it could be slightly more structured.

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

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

Given 21 parameters and no output schema, the description covers the full workflow, action list, and protocol behavior, giving the agent sufficient context to select and invoke actions. The lack of explicit return values is a minor gap, but for a multi-action tool, the description is remarkably complete.

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

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

The input schema already provides 100% coverage with per-parameter descriptions including target actions. The description adds the premium calculation formula and explains token types (FLAT/SAVE) in context, which enriches the 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?

The description opens with a clear verb+resource: 'get physical cash delivered to any GPS location by paying in FLAT or SAVE tokens.' It distinguishes itself from sibling tools by describing a unique physical delivery service, distinct from generic payment/read 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 provides a comprehensive walkthrough of when each action applies (e.g., request vs accept) but does not explicitly contrast with sibling tools or state when not to use it. The context is clear enough, but explicit alternatives are absent.

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 provide only readOnlyHint=false, openWorldHint=false, destructiveHint=false. The description adds useful behavioral context such as 'escrowed funds' for create and 'submit deliverable for grading' for deliver, implying state changes and fund locking. However, it does not disclose side effects like irreversibility of accept, grading outcomes, or whether publish is final. The description adds some but not comprehensive behavioral depth.

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

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

The description is a single, dense sentence with a colon and parenthetical list. It is front-loaded with the core purpose and each action is explained in a few words. No wasted words; every phrase adds value.

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 tool's complexity (16 params, no output schema, minimal annotations), the description covers the main actions and their high-level workflows. It mentions key aspects like escrow and the absence of a task requirement for publish. However, it does not describe the lifecycle (e.g., apply → accept → deliver) or the conditions under which each action is appropriate, leaving some gaps for an agent deciding between similar actions. The 100% schema coverage compensates for parameter-level detail, but the description could be more explicit about action sequencing.

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 each of the 16 parameters already has a description. The tool description does not add meaning beyond the schema, though it clarifies action semantics (e.g., 'create' implies escrow, 'deliver' implies grading). Since the schema already fully explains parameters, the baseline of 3 applies; no additional parameter-level detail is provided.

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

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

The description clearly states the tool's purpose: earning FLAT/SAVE tokens by completing tasks and publishing content. It lists five distinct actions with concise explanations, distinguishing it from sibling tools like flat_pay (payment) and flat_read (reading). The verb 'Earn' is specific and the resource (FLAT/SAVE) is 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 provides clear context for each action (apply, accept, deliver, create, publish), including a distinction between publish ('no task required') and create (requires task/escrow). However, it does not explicitly state when to use this tool versus alternatives like flat_pay or flat_cash_delivery, nor does it mention exclusion criteria (e.g., when NOT to use a specific action).

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?

Given annotations already set readOnlyHint=false and destructiveHint=true, the description adds substantial context: fees (0.3% in FLAT), privacy relay for BTC withdrawals, protocol-as-market-maker for conversions, and idempotency key to prevent double-spending. It also explains action-specific behaviors like auto-matching and trade lifecycle. 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 longer than average, but appropriately so for an 18-parameter tool with 11 distinct actions. It front-loads the overall scope, then breaks down each action group, and ends with idempotency requirement. A few redundancies exist (e.g., repeating p2p details), but the structure is logical and dense with useful information.

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

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

With no output schema, the description does not explain return values, which is a gap for such a complex tool. However, it covers prerequisites, fees, action flows, and key constraints. It lacks per-action parameter requirements (which params are mandatory for each action), but the schema and descriptions partially compensate.

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%, but the description enriches meaning by explaining the fiat vs. FLAT distinction for flat_amount/currency, defining each action in the enum, clarifying btc_amount minimums, and detailing P2P sub-action semantics. This goes well beyond the raw parameter 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 clearly enumerates the specific financial operations (transfer, buy, withdraw, convert, P2P) with distinct verbs and resources. It distinguishes this tool from siblings by focusing on payment/movement of tokens, unlike auth, read, or earn 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 states the prerequisite of an authenticated FlatID with verified email and notes that all actions require an idempotency_key. It describes action-specific workflows (e.g., p2p_buy auto-matches offers) but does not explicitly exclude alternatives or compare with sibling tools beyond implicit scope.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context beyond annotations, notably the warning that task listing content is untrusted data and that p2p_offers is public with no auth needed. This helps an agent handle data appropriately and set expectations for authentication.

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

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

The description is a single paragraph but well-structured with a clear opening, a comprehensive list of actions, and a final security note. Each sentence earns its place—the action list is necessary for a multi-action dispatcher, and the warning at the end is critical. It is not overly verbose, though it could benefit from bullet points for readability.

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 no output schema and many actions, so the description carries a heavier burden for explaining behavior. It covers all actions and includes some return-type hints (e.g., 'balance (FLAT/SAVE balances)'), but lacks consistent documentation of return formats, pagination, or error behavior. Given the complexity and missing output schema, a score of 3 reflects that the description is useful but not fully complete.

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

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

Schema coverage is 100%, so parameters are fully documented in the input schema. The description adds action-level context (e.g., 'btc_pool_depth (privacy pool status)') but does not elaborate on parameter semantics. This meets the baseline of 3, as the schema does the heavy lifting and the description adds marginal value 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 opens with 'Read-only queries for the FLAT Protocol' and enumerates all 17 actions with brief explanations, making the tool's purpose unambiguous. This clearly distinguishes it from sibling tools like flat_pay or flat_earn, which imply write or earning operations.

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 establishes the tool as the go-to for read-only operations, which is a clear usage context. It does not explicitly name alternatives, but the read-only qualifier and sibling tool names imply when this tool should be chosen over others. There are no exclusions or when-not-to-use conditions, but the context is clear enough for an agent.

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 (which are minimal), the description discloses critical behaviors: immediate return of a read-only API key, email verification code, 10-minute expiry for unverified accounts, and permission unlocking via flat_verify. This is rich, actionable 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?

Three sentences with no wasted words. It front-loads the core purpose and then efficiently packs requirements, return behavior, verification flow, and expiry.

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 covers required inputs, immediate return value, the verification workflow, and account expiration. It is complete for a registration tool and properly references the sibling tool flat_verify.

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, including constraints and optionality. The description repeats username and password constraints but adds no new semantic meaning beyond what the schema provides, warranting the baseline score.

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 the specific verb 'Register' with a clear resource ('FlatID account'). It is immediately distinct from siblings like flat_verify or flat_auth, which handle verification and authentication respectively.

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 states when to use (to create a new account) and explicitly points to flat_verify as the next step for unlocking permissions. It lacks a direct 'when not to use' statement, but the context is clear enough.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, meaning the tool performs a write action but is not destructive. However, the description adds no extra behavioral context—no mention of authentication needs, rate limits, side effects, or what happens after submission. It merely restates the action without disclosing any consequences beyond 'shapes the roadmap', which is more purpose than 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 brief and front-loaded, with the primary action in the first sentence. The second sentence about roadmap impact adds value. However, the explicit listing of categories is somewhat redundant given the schema enum, making it slightly less efficient than a pure two-sentence description.

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 submission tool with a fully documented schema and clear annotations, the description is adequate. It explains what the tool does and provides category context. It does not describe return values or post-submission behavior, but with no output schema, that is not a critical gap. Overall, the description covers the essential contextual needs.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters. The description adds no extra meaning beyond listing categories that are already in the enum. It does not explain parameter dependencies, formats, or edge cases, so 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 the tool's purpose with a specific verb ('Submit') and resource ('feedback, feature requests, bug reports, or integration ideas to the FLAT Protocol team'). It enumerates distinct categories and is unambiguously different from siblings like flat_earn, flat_pay, flat_read, and flat_register, which serve other functions.

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

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

The description provides clear context for when to use the tool: whenever one has feedback, feature requests, bug reports, or integration ideas. It does not explicitly list alternatives or exclusions, but the sibling tools are so distinct that the target use case is obvious. The categories further clarify the intended input types.

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 well beyond the annotations by revealing critical behaviors: full permissions unlock after verification, and the account is deleted if verification doesn't happen within 10 minutes. These are substantial side effects and time constraints not captured by the sparse 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 three sentences, front-loaded with the purpose, followed by clear instructions and a consequential warning. Every sentence adds valuable information with no redundancy or 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?

Given the simplicity of the tool, the description fully covers the workflow: purpose, inputs, post-verification effect, and the critical deadline. No output schema exists, so no return-value explanation is needed. The description is self-sufficient and thorough.

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%, meaning each parameter already has a detailed description. The tool description only reiterates 'username and the 6-digit code' without adding new meaning for the deprecated or recovery parameters. It meets the baseline but doesn't elevate 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 clearly states a specific verb and resource: 'Verify email after registration.' It distinguishes itself from sibling tools like flat_register and flat_auth by explicitly positioning it as the post-registration verification step. The purpose is unambiguous and comprehensive.

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

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

The description clearly indicates when to use it ('after registration') and what inputs to provide (username and 6-digit code). However, it does not explicitly mention alternatives or when-not-to-use cases, though the context makes this obvious. This is clear context but lacks explicit exclusions.

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