Flat Cash

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

The description discloses important behavioral details beyond the annotations, including that password login produces a fresh API key with full permissions, token action verifies an existing key, and the interactive flow requiring username first and offering to store the password in environment variables. Annotations are sparse and non-contradictory, so the description carries the burden well.

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

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

The description is compact and front-loaded with the core purpose. It then provides action breakdowns and crucial interaction instructions in just three sentences, with zero fluff. Every sentence contributes to understanding how to use the tool.

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

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

Despite having no output schema, the description covers the tool's two modes, expected inputs, outcomes, and even the conversational flow for credential gathering. It is complete enough for an agent to confidently invoke the tool and handle user interaction, covering security-sensitive aspects effectively.

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 value by clarifying how parameters relate to the 'action' field (e.g., username/password required for 'password', api_key for 'token') and the consequence of using them (fresh API key with full permissions). This 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 clearly states the tool authenticates an existing FlatID user, which is a specific verb+resource. It also distinguishes itself from siblings like flat_register (new accounts) and flat_verify (verification) by focusing on login and token verification.

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

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

The description explicitly says to use this if the agent already has a FlatID account, giving a clear usage context. It also provides action-specific guidance (password vs token). However, it does not explicitly name alternatives like flat_register for new accounts or flat_verify for verification, so it stops short of full when-not-to-use guidance.

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

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false; no contradiction). The description adds behavioral context by detailing each action's purpose (e.g., 'create' escrows funds, 'publish' submits to community page). However, it omits side effects like state changes (e.g., applying decrements a slot) 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 two sentences with a bullet list of actions. It front-loads the main purpose, then succinctly defines each action. Every sentence is informative; no wasted words.

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

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

Given the complexity (15 parameters, 5 actions, no output schema), the description covers the essential actions and their intents. It could more explicitly link actions to required parameters (e.g., 'for create, use title, description, amount...'), but the schema already handles that. Overall, it provides sufficient context for an agent to understand what the tool does and start using 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 baseline is 3. The tool description does not add parameter detail beyond the action list (which maps to relevant parameters implicitly). The schema already documents each parameter's purpose and constraints, so the description contributes minimal extra semantic value.

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

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

The description explicitly states the tool's purpose: 'Earn FLAT/SAVE by completing tasks and publishing content.' It enumerates five specific actions (apply, accept, deliver, create, publish) with brief definitions, clearly distinguishing it from sibling tools like flat_pay (payments) and flat_read (reading).

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 when to use each action (e.g., 'apply for a task', 'create: post a new task with escrowed funds'), but does not explicitly state when not to use this tool or guide the agent to alternatives among siblings. No comparison with flat_pay, flat_read, or flat_register is offered.

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 readOnlyHint=false, so the mutation/safety profile is covered. The description adds meaningful context: idempotency_key requirement to prevent double-spending, email verification requirement for P2P, 0.3% FLAT fee on btc_withdraw, privacy relay behavior. However, it doesn't disclose return values, confirmation flows, or error cases, and since there's no output schema, more behavioral detail would be valuable for an 18-param 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 quite long and dense, packed into a single paragraph. It front-loads the core purpose well, but the P2P sub-action enumeration and btc_withdraw details would benefit from structured formatting (bullets or line separators). The length is justified given the tool's complexity (9 sub-actions, 18 params), but the lack of structure hurts scannability.

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 this is a very complex multi-action tool with no output schema and only sparse annotations, the description does a strong job covering prerequisites (login, email verification), sub-action workflows (P2P order of operations), and safety mechanisms (idempotency_key). It could describe return values or post-action states, but for a tool this complex the description is notably 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 description coverage is 100%, so the schema already documents all 18 parameters thoroughly. The description does add some value: it explains the privacy relay mechanism for btc_withdraw and clarifies idempotency purpose. But most parameter meaning (currency conversion, ranges, formats) lives entirely in the schema, which is the baseline expectation. The description doesn't substantially add beyond the schema for parameters.

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

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

The description clearly states the tool performs financial operations (transfer, buy, withdraw, btc_withdraw, P2P exchange) with specific verbs and resources. It enumerates each action explicitly which helps differentiate from flat_read (read-only), flat_auth/register (auth), flat_earn (earn). However, it bundles many actions into one tool, making the primary purpose somewhat broad rather than singular.

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?

Excellent guidance: explicitly states NOT to call until user is logged in with verified FlatID, tells the agent to first walk through registration/login using flat_register or flat_auth as a prerequisite, names the specific alternative tools. Also lays out the P2P workflow sequence (p2p_buy → p2p_confirm → p2p_release) which is strong use-context guidance. Distinguishes when to use which sub-action clearly.

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 established. The description adds meaningful context by listing all available actions and notably includes the security warning that task listing content is untrusted user data — this is genuine behavioral value beyond the annotations. It doesn't cover rate limits, pagination, or error behaviors, but the security caveat elevates it above baseline.

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?

One dense paragraph front-loads the purpose and enumerates actions compactly. The parenthetical explanations per action are efficient and informative. It's long due to 17 actions, but each earns its place. Slight deduction for a run-on structure that could benefit from a list format, but the content density justifies the 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?

For a multi-action dispatcher with 11 parameters and no output schema, the description is thorough — it documents all actions, maps key parameters to their actions, includes defaults (limit, status, currency, token_type), and adds a security caveat. The param-to-action mapping is not complete for all 11 params, but given the schema covers param semantics, the description is reasonably complete for the tool's complexity.

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

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

Schema coverage is 100%, so all 11 parameters already have descriptions. The description adds value by mapping which parameters apply to which actions (e.g., task_id required for task_detail, trade_id required for p2p_status, eth_amount for buy_quote, token_type/currency/delivery_method for P2P). This cross-referencing of params to actions significantly aids selection, though it's not exhaustive for every action.

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 this is a read-only query tool for the FLAT Protocol and enumerates 17 specific actions with parenthetical explanations. It distinguishes itself from sibling tools (flat_auth, flat_pay, flat_earn etc.) by covering all read operations under one tool. However, it doesn't have a single crisp verb+resource summary since it's a multi-action dispatcher, though the action list compensates.

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

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

The description explicitly notes that p2p_offers is PUBLIC and requires no auth, which is a useful usage distinction. It clearly frames the read-only nature versus siblings like flat_pay (mutations). However, it doesn't explicitly state when NOT to use this tool vs. alternatives like flat_auth for authentication actions, leaving some cross-tool guidance implicit.

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

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

Despite annotations being sparse (readOnlyHint=false, destructiveHint=false), the description adds significant behavioral context: 6-digit codes are sent to both emails, verification must occur within 10 minutes, and the account is deleted if not verified. It also mentions the post-verification celebration and password storage offer, going far beyond the annotations.

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

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

The description is somewhat long but well-structured with clear sections (IMPORTANT, REQUIREMENTS, After calling, After verification). Each sentence carries useful information, and the front-loaded purpose makes it scannable. A slight trim could improve conciseness, but it remains effective.

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 entire lifecycle: pre-call conversational requirements, call-time validation, post-call verification flow, and post-verification actions. With no output schema, the description still gives the agent enough context to handle the tool correctly, including failure consequences and next steps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates requirements (emails must differ, password minimum) but does not add novel per-parameter semantics beyond what the schema already provides. The added value is mostly in workflow, not parameter meaning.

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 begins with 'Register a new FlatID account,' which uses a specific verb ('Register') and resource ('FlatID account'). It clearly distinguishes from sibling tools like flat_verify and flat_auth by focusing on account creation.

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

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

The description provides explicit usage timing: 'Do NOT call this tool until you have asked the user for EACH field one at a time' and outlines the exact sequence. It also references flat_verify for post-call verification, giving clear guidance relative 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?

Annotations already indicate it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), so the description need not restate those. It adds a minor claim ('Your input directly shapes the product roadmap') but does not disclose operational behaviors like whether a confirmation is returned or any rate limits. With annotations covering the safety profile, a 3 is appropriate.

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 and front-loaded with the primary purpose. The second sentence includes a somewhat fluff statement about shaping the roadmap, but it is brief and does not bloat the description. It earns a 4 for efficiency and clear structure.

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 feedback-submission tool with no output schema, the description covers the core purpose and enumerates the categories. It does not explain what happens after submission, but that is not critical for invoking the tool. The description is complete enough for an agent to decide when to use it.

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

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

Schema coverage is 100%, meaning every parameter has a description in the schema. The tool description repeats the category enum but does not add any meaning beyond what the schema already provides. The baseline 3 is warranted.

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

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

The description uses a specific verb ('Submit') and clearly identifies the resource ('feedback, feature requests, bug reports, or integration ideas to the FLAT Protocol team'). It distinguishes this tool from siblings like flat_earn, flat_pay, flat_read, and flat_register by focusing solely on feedback submission.

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 implies this tool is for submitting feedback and ideas to the team, which differentiates it from the transactional siblings. However, it does not explicitly mention when not to use this tool or name alternative tools, so it stops short of a 5.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral context: 'BOTH must be verified within 10 minutes or the account is permanently deleted and the username freed.' It also reveals that full permissions unlock only after both verifications and outlines post-verification behavior (celebrate, confirm FlatID, offer to store password). This goes beyond the annotations without contradicting them.

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

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

The description is longer than minimal but each sentence serves a purpose: what it does, how to invoke, deadline, permission unlock, and post-verification actions. The 'AFTER SUCCESSFUL VERIFICATION:' marker structures the final section. It is not wastefully verbose, though it 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 tool has 3 parameters, no output schema, and minimal annotations. The description covers the purpose, the input semantics, the time-sensitive constraint, the consequence of failure, and even post-verification next steps. It is complete enough for an agent to execute correctly and handle the outcome, despite not specifying a return value.

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

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

Schema description coverage is 100%, with each parameter already well-described ('6-digit code sent to your primary email' etc.). The description adds usage semantics (providing both codes in one call or one at a time) but does not add new parameter-level meaning beyond the schema. 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 opens with a specific verb and resource: 'Verify BOTH emails after registration.' It clearly distinguishes this tool from siblings like flat_register (registration), flat_auth (authentication), and flat_read (reading). It also clarifies the exact scope: both primary and recovery emails must be verified.

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

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

The description explicitly states the context: 'after registration.' It also provides two usage patterns: 'call this once with both codes, or twice (once per code).' It does not explicitly name alternative tools, but the context is clear enough to avoid confusion with siblings. The mention of 'full permissions unlock only when both are confirmed' implies when to use this as a prerequisite.

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