registry_upsert

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

With no annotations, the description carries the full burden and discloses the key behavioral traits: all writes go to staging and the formal registry is untouched until kind='commit'; commit can be previewed and rolled back; duplicate writes with changed grades append conflicts; protocol writes preserve user-modified copies as protocol.md.new; insight writes are scanned and rejected on injection signals; and records are normalized before persistence. These are meaningful behaviors beyond anything in the schema.

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 definition is front-loaded with purpose and the critical staging/commit gate, then uses kind-based bullets so an agent can scan to the relevant mode. It is long, but the length is largely justified by ten distinct record kinds and two cross-cutting warnings; a few rhetorical or emphatic phrases could be trimmed without losing 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, ten modes, absent schema descriptions, and no annotations, the description is complete enough to call correctly: it covers staging semantics, commit/discard lifecycle, run-start bookkeeping, per-kind payloads, normalization behavior, injection handling, and readback paths. An output schema exists, so the description reasonably does not need to enumerate return values in detail.

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% and the schema exposes only kind, topic, and records, so the description must compensate, and it does: it defines all ten kind values and gives the expected record shape for source, video, insight, topic, protocol, cluster, rejected, commit, discard, and run-start records. It also clarifies when topic is required, that records are not needed for run-start, and that malformed topics/domains/key_findings will error rather than be silently written.

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 a specific verb and resource, '写资产库', and enumerates ten record kinds, so the agent knows this is the write/upsert path for the registry. It refers to the readback sibling registry_get and to scan_topic, but never gives a single explicit contrast sentence such as 'use registry_get to read; use this to write staging records', leaving sibling differentiation partly implied.

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?

Usage conditions are unusually explicit: call at the end of every task, call kind='run-start' once at phase 0 end, call kind='commit' once at wrap-up in the fixed commit → paste final_cost → render order, and use kind='discard' to throw away staging. It also states that rejected candidates must be recorded through this tool and names registry_get(kind='rejected')/scan_topic(exclude_bvids=...) as the downstream read/use path, so alternatives and timing are clear.

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