publish_note

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

Annotations already declare write (readOnlyHint=false), open-world and idempotent behavior; the description adds real context beyond that: a user-confirmation gate, the consent semantics of accept_terms, and a no-retry rule. The no-retry advice sits in slight tension with idempotentHint=true, but it reads as operational caution (avoid acting on an ambiguous outcome) rather than a factual conflict with the annotation.

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 dense sentences, front-loaded with the action and then the gating conditions. Every sentence carries a distinct constraint (user confirmation, terms consent, no resubmit), with no filler. Slightly terse given the mutation risk, but not padded.

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 non-idempotent-looking publish step with no output schema, the description covers the preconditions and the ambiguous-result case, which is the main risk. However, it does not say what a successful submission returns or returns a job handle, and it omits the obvious resolution path (get_publish_status) that an agent needs when the result is unclear.

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 0%, so the schema supplies names and types only. The description meaningfully explains accept_terms (explicit user consent to Trip.com material-ownership and platform terms), and '已预览的笔记' hints that job_id refers to a prepared note, but it never explains job_id's origin or what confirm actually gates. Partial compensation for a 3-parameter, 0%-coverage schema.

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+resource is specific: submit ('提交') a previously previewed note ('已预览的笔记'), which tells an agent this is the terminal publish step, not preparation. It does not name its closest siblings (prepare_note, get_publish_status), so the distinction must be inferred from the '已预览' wording. Clear, but sibling differentiation is left implicit.

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 an explicit precondition (only after the user confirms the target account and specific content) plus two constraints: accept_terms requires explicit user consent to material ownership/platform terms, and no resubmission when the outcome is unclear. It stops short of naming get_publish_status as the way to resolve an unclear result, so the recovery path is implied rather than stated.

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