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

Annotations already declare read-only, idempotent, and non-destructive. The description adds valuable context about data source (NEAR RPC priced by NEAR Intents), output behavior (count of scanned tokens, exclusion of others), and operational traits (no wallet/API key required, pricing per call). 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 a single paragraph but each sentence earns its place: purpose, inclusions, exclusions, data source, pricing, and authentication. The core purpose is front-loaded, and the rest provides necessary operational details without padding.

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?

Covers the essential aspects: what the tool returns (sorted balances, total, count of scanned tokens), the data freshness (live), pricing and auth requirements. Given an output schema exists and the single parameter is simple, the description is sufficient for an agent to call it correctly. Minor gaps like error handling for invalid accounts are not critical.

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

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

The only parameter is 'account' and the schema gives a minimal description 'NEAR account.' The tool description repeats 'Required input: account' and adds 'No wallet or API key required,' but does not clarify the expected account format (e.g., 'example.near' or a public key). It adds little semantic value over 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?

States exactly what it computes (net worth of a NEAR account), the specific asset types (NEAR liquid and staked, NEP-141 tokens like USDC, USDT, wNEAR), and the valuation method (USD, sorted by value). The scope limitation ('tokens outside that list are not included') further distinguishes it from generic portfolio tools.

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

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

The description gives clear context of what it covers and its limitations (only NEAR Intents routed tokens), but never explicitly names alternatives like wallet_networth or b20_portfolio nor states when to prefer this tool over them. Usage is implied rather than stated.

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