nayori_client_set_budget

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

Annotations only mark readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds that this is a 'WRITE (mainnet)' operation, that it 'only records a number', that it 'does NOT pay anything', that it is refused unless the signer is the client on an open job, and that it 'Returns a txid; broadcast is not confirmation.' These behaviors are not derivable from the annotations and provide critical transparency.

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 yet information-dense, starting with the dominant purpose and then layering precondition, limitation, and return semantics. Every sentence adds a distinct fact with no filler; only the atomic-units sentence partially duplicates the schema's amount description, which is a minor 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?

With no output schema, the description supplies the return type ('txid') and the critical caveat that broadcast is not confirmation. It also covers the mainnet context, the refusal condition, and the limitation that funding is a human wallet action. For a mutating blockchain tool with sparse annotations, this is a complete and thorough definition.

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 only 33% (only amount has a description). The description reinforces the atomic-units rule and adds that the amount is a recorded number, not a payment. It also contextualizes jobId as referring to 'a job you created', which is absent from the schema. Asset still relies solely on its enum values, so parameter semantics are improved but not fully elaborated.

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 'WRITE (mainnet)' and 'Act as a CLIENT: declare the budget of a job you created (escrow set-budget)', stating the exact action, actor, and underlying mechanism. It explicitly clarifies that it does not pay anything, which distinguishes it from a payment operation, and the sibling list confirms it is the only budget-setting tool.

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 concrete usage preconditions: 'Refused unless a fresh read shows the signer is the job's client and status is 0 (open)' tells the agent exactly when this tool is valid. It also warns that 'Funding the escrow afterwards is a human wallet action that this server cannot perform', preventing misuse as a payment tool. It does not name an alternative sibling, but the conditions are explicit and clear.

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