Move a task, outline, or elective to a specific position using a zero-based sort_order, including into a different outline of the same learning path.
Verschiebt eine Aufgabe/Gliederung/Wahlpflicht an eine Position (sort_order, 0-basiert) – auch in eine andere Gliederung desselben Lernpfads.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| parent_id | Yes | Ziel-Gliederung/-Lernpfad | |
| sort_order | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden: it does disclose that this is a relocation operation with 0-based ordering and that cross-Gliederung moves are allowed only within the same Lernpfad. It does not disclose whether items at the target position are shifted or overwritten, whether permissions are required, or what is returned, which are significant gaps for a mutation tool.
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?
A single dense sentence; the verb and affected resources come first, with the destination and scope constraints front-loaded in the parenthetical. Nothing is redundant or 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 3-parameter mutation with no annotations and no output schema, the description covers the key semantics (0-based index, same-Lernpfad constraint) but omits reordering side effects and return behavior. Adequate, but an agent still has to guess at edge-case behavior.
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 coverage is only 33%, so the description must compensate. It does so meaningfully: it defines sort_order as 0-based (absent from the schema) and clarifies that id refers to the moved Aufgabe/Gliederung/Wahlpflicht while parent_id is the destination Gliederung. Only the id parameter's type/expectations remain thin, keeping it from a 5.
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 names a specific verb ("Verschiebt") and the exact resources affected (Aufgabe/Gliederung/Wahlpflicht), plus the destination concept (Position via sort_order, or another Gliederung). This is clearly distinguishable from the sibling update_* tools, which edit content rather than relocate items, though no sibling is named explicitly.
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 parenthetical "auch in eine andere Gliederung desselben Lernpfads" usefully constraints scope (same Lernpfad only), which functions as an implicit when-not rule. However, it never states when to pick this over scobees_update_aufgabe/update_gliederung or what to do if the move crosses Lernpfade.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.