knowledge_update

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

No annotations are provided, so the description carries the full disclosure burden, and it does reveal meaningful behavior: partial-update semantics ("Only given fields change"), the conditional requirement that norm_entschieden_grund becomes mandatory when norm_entscheidung is given, and the side effect that betreiber_weisung "records the operator as decision-maker." However, for a mutation tool it omits standard behaviors an agent needs — reversibility, response/error shape, permissions — and does not say whether updates ripple into related entities like trust scores.

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 core purpose is front-loaded in the first clause and every subsequent clause carries a distinct constraint or dependency — there is no filler or repetition of the schema. It is, however, one dense run-on paragraph built on em-dashes and parentheticals, which taxes careful reading and slightly hurts scannability.

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 15-parameter mutation tool with no output schema and no annotations, the description covers the convoluted norm_entscheidung conditional thoroughly, which is the highest-risk part of calling this tool. But it omits the return value, failure/validation behavior, and broader side effects, so an agent cannot predict what a successful call returns or what else changes downstream.

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 80% (nearly all parameters documented, with the three bare ones being self-explanatory tags/summary/content), so the baseline is 3. The description earns the extra point by adding cross-parameter meaning: it groups the mutable field families, defines partial-update semantics, explains the gilt_bis/norm_entscheidung contradiction rule, and states the norm_entschieden_grund dependency — relationships the flat schema cannot express.

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?

Opens with the specific verb+resource pairing "Update an existing knowledge node" and enumerates exactly which aspects change (title, summary, content, tags, Normschicht fields). It differentiates from the sibling knowledge_add by targeting existing nodes and even cross-references knowledge_add for field meanings, so an agent can route correctly without opening either schema.

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 update-vs-create context is clear from "existing knowledge node" and the explicit contrast "unlike knowledge_add" for norm_entscheidung. Cross-parameter when-conditions are precise, e.g. "only needed when the change would otherwise contradict the node's existing decision" with a concrete gilt_bis example. It stops short of stating exclusions (e.g., don't use this for creation) or alternatives for node-vs-relation updates, so the guidance is context-rich but not fully explicit.

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