chainpeek: a NEAR account's balance, staked NEAR, storage, access keys and whether it has a contract

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

Adds substantial behavior beyond the annotations: unknown accounts return exists=false and are charged, bad account ids return 422, failed RPC reads return 503 and are not charged, pool delegations are excluded from locked_near, key and method strings are untrusted, plus latency, price, and free-tier limits. The annotations already declare readOnly/idempotent/non-destructive, and the description is fully consistent with 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?

Front-loads the core purpose and the EVM alternative, then layers return details, error behavior, pricing, limits, and security warnings. Mostly earns its length, but there is minor redundancy between 'Key and method strings are untrusted' and the later untrusted-data warning, and the docs URL appears unrelated to this 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?

For a read-only account-state tool with both annotations and an output schema, the description supplies all needed invocation context: network and finality assumptions, error and charging semantics, return boundaries, latency, pricing, free-tier limits, and untrusted-data handling. Return-value explanation is technically extra given the output schema but remains consistent and helpful.

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 the accepted account_id formats: named accounts, 64-hex implicit accounts, and 0x+40-hex ETH-implicit accounts, case-folded. The description adds no further parameter-level syntax or constraints, 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, 'Get a NEAR account', and enumerates the returned fields: balance, staked NEAR, storage, access keys, and contract status. It explicitly names the sibling alternative get_portfolio for EVM balances, so an agent can distinguish it from other account-state 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?

Gives a clear use context for NEAR account state and names get_portfolio as the alternative for EVM balances. It also sets boundaries such as 'no history' and 'Mainnet, final finality', but does not provide a full when-not list against other account-related siblings.

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