Venice x402 Wallet Balance

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

With no annotations provided, the description carries full burden. It discloses that API key auth is rejected, that the SIWX token must be forwarded, and crucially that the wallet in the path must match the SIWX-authenticated wallet — a key constraint that would cause failures if unknown. This is meaningful behavioral context beyond the parameter schema.

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

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

Two concise sentences that are front-loaded with the core purpose, followed by the critical auth constraint. Minimal waste, though the SIWX detail could be slightly condensed. Efficient overall.

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

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

For a single-parameter, no-output-schema tool, the description covers the essential points: what it does, the auth requirement, and the critical wallet-matching constraint. It doesn't describe the response format, but with no output schema and a simple balance check, this is a reasonable gap. Slightly more on what the returned balance represents could help, but it's largely 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 0%, so the description must compensate. The description explains the wallet_address parameter's role (must match the SIWX-authenticated wallet) which adds semantic constraint beyond the hex pattern in the schema. The wallet format is already enforced by the schema pattern, so the description's added value is the matching constraint.

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 checks the 'prepaid x402 credit balance for a wallet address' — a specific verb (check), resource (prepaid x402 credit balance), and target (wallet address). It also distinguishes from siblings like venice_x402_transactions and venice_x402_top_up_info by focusing on balance checking.

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

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

The description explicitly states when not to use it: 'SIWX-ONLY: this endpoint rejects API key auth and requires X-Sign-In-With-X (forwarded from VENICE_SIWX_TOKEN).' This is clear context about authentication prerequisites. It doesn't explicitly name alternative tools, but the auth constraint is the primary usage gate, which is well communicated.

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