pandaone_write

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

Annotations already carry destructiveHint=true, indicating a mutating operation. The description adds useful behavioral context by requiring reason/problem/approach as an audit trail and by separating text and binary write modes. It does not contradict the annotations and provides meaningful extra process-level detail.

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 entire description is one dense sentence that front-loads the tool's role as the core write command and packs all essential mode guidance into a compact, scannable format. There is no redundant or filler content.

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 10-parameter destructive write tool with no output schema, the description covers mandatory fields and parameter mode groups but omits important constraints such as whether --old and --new must be supplied together, whether the text and binary modes are strictly exclusive, and what postcondition the write operation guarantees. It is useful but not fully complete.

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?

With 90% schema description coverage, the baseline is 3. The description adds value by grouping parameters into two mutually exclusive usage modes (text vs binary), which is not explicitly encoded in the schema. This helps the agent select the correct parameter group for the intended write operation.

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 identifies the tool as an audit-driven write command ('审计写入（核心命令）'), stating the core action and the key mandatory audit fields. It does not explicitly differentiate from sibling tools like pandaone_ci or pandaone_lock, but the write intent is 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 gives clear mode-selection guidance: text should use --old/--new or --content, and binary should use --from-file or --content-base64. However, it does not explain when to use this tool versus sibling alternatives, beyond calling it the 'core command', so the alternatives guidance is only implied.

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