sync_balance

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

With no annotations, the description carries the full burden, and it does disclose valuable behavior: a two-phase flow starting with an empty object, intermediate browser instructions, and a success gate ('report success only when the result says synced'). It does not disclose side effects, permissions, reversibility, or what data is transmitted — significant gaps for what appears to be a state-changing operation.

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?

Three short sentences, front-loaded with the trigger condition and sequenced in execution order. Dense and largely waste-free, though 'start with {}' is terse to the point of being cryptic.

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 two-call protocol and success condition are covered, and there is no output schema to explain. But for a 4-parameter, unannotated tool with no safety metadata, the description omits what the sync actually does, what happens on failure, and whether re-invocation is idempotent.

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 per-field meaning is handled there. The description adds real value beyond the schema by clarifying that the first call takes no arguments and the second requires all four fields — notable because the schema declares zero required parameters, so without this the agent would not know all four are expected.

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 verb 'sync' and resource 'balance' are named and the trigger phrases distinguish it from siblings like get_spending, but the description never says what is being synced to where or why. The three sentences describe a call protocol rather than the operation's purpose, leaving the actual effect ambiguous.

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?

It gives explicit invocation triggers ('同步余额' or 'sync my balance'), which is stronger than most definitions. However, it never says when NOT to use it or contrasts it with get_spending, which an agent could plausibly pick for a balance-related request.

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