save_bill

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

The description discloses several behavioral traits: automatic normalization of tags to JSON string, defaulting recordTime to updateTime/current time, and regenerating billId if it exceeds int32. These go beyond what annotations (none provided) offer. It does not cover error handling or side effects, but the disclosed behaviors are valuable. Since annotations are absent, the description carries the burden and does a good job.

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 comprehensive but dense. It front-loads the core purpose (add/update) and the normalization behaviors, then lists all fields in a compact paragraph. It is not overly long for the complexity of the bill object, but the field listing could be more structured (e.g., bullet points) to improve readability. It earns each sentence by providing essential information.

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?

Given the tool's complexity (many nested fields, auto-normalization rules), the description covers the essential information: how to distinguish update vs. add, automatic behaviors, and a full field breakdown. It lacks output return details, but there is no output schema, and the caller likely needs to know the operation succeeded; that is a minor gap. Overall, it is sufficiently complete for an agent to invoke it correctly.

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 input schema has 100% description coverage, as it says '账单对象，见描述字段说明' (bill object, see field descriptions in the description). The description elaborates extensively on each field of the bill object, adding meaning beyond the minimal schema. Since schema_coverage is high, baseline is 3, and the description does provide value, but it doesn't significantly exceed the baseline because the schema already points to it.

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's purpose: creating or updating a bill via an upsert endpoint, with explicit details on how the addition/update is differentiated (presence of billId). It distinguishes from sibling tools like save_bills and delete_bill by specifying the single-bill upsert operation. The verb and resource are clear, though it doesn't explicitly name siblings, the API path and behavior make the purpose unambiguous.

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 implies usage: use this tool when you need to add or update a single bill, as opposed to save_bills for batch operations or delete_bill for deletion. It provides the condition for update vs. add (billId presence). It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to infer the appropriate tool.

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