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

No annotations are provided, so the description carries the full burden. It usefully discloses that content is supplied either as Markdown with specific quiz block types or as a finished serlo_json, and that attachments are added afterwards via another tool. It says nothing about permissions, validation failures, or what happens when both content fields are passed.

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 placement, then the art taxonomy, then the content format, then the follow-up call. No filler; only minor cost is that the art enumeration is compressed into a run-on list.

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 an 11-parameter mutation tool with no annotations and no output schema, the description covers the two decisions that matter most (which art, which content format) and implicitly clarifies that `parent_id` is the id of a Gliederung/Wahlpflicht/Lernpfad. The interaction between differenzierungen, wahlaufgabe and art is left to the schema, which is a minor gap.

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 64%, and the description adds real value beyond it by defining each `art` enum value (info/selbstkontrolle/abgabe_*) and by enumerating the quiz block names accepted in `arbeitsblatt_markdown`, plus the serlo_json alternative. It leaves `links`, `wahlaufgabe`, `interne_notiz` and `estimated_time` entirely to the 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?

States a specific verb+resource ("Legt eine Aufgabe ... an") and names the three container types it can be created in (Gliederung/Wahlpflicht/Lernpfad), which cleanly separates it from siblings like scobees_create_gliederung or scobees_create_lernpfad. An agent can identify the tool without opening the 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?

Gives the placement contexts and a concrete follow-up step ("Dateien danach mit scobees_upload_material anhängen"), so the agent knows the workflow. It stops short of saying when to prefer scobees_update_aufgabe or scobees_markdown_vorschau instead, so no explicit exclusions.

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

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. 'Legt ... an' signals a mutation, but nothing is said about required permissions, what the response contains (e.g. the new ID), ordering/index behavior, or what happens on failure. The only substantive note is about HTML input format, which is really parameter guidance.

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?

Two short sentences with the core purpose front-loaded and the HTML format note second. No filler, though the format note could be trimmed by referencing the schema field name to tie it to a parameter.

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 create tool with no annotations, no output schema and only 3 parameters, the description covers purpose and input format but omits return information, prerequisites (does the parent need to exist in a specific state?) and any conflict/ordering rules. Adequate but leaves real gaps.

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 33% — only parent_id ('Lernpfad- oder Gliederungs-ID') is documented in the schema. The description compensates for description_html by enumerating allowed tags (h2, p, strong, em, u, a, span style=color), but the 'name' parameter is left completely unexplained and the description_html default of '' is not mentioned.

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?

Uses a specific verb ('Legt ... an') plus a concrete resource ('Gliederungsstruktur (Ordner/Phase)') and names the two possible parent contexts (Lernpfad or another Gliederung). This clearly separates it from siblings like scobees_create_lernpfad or scobees_create_aufgabe, though it never explicitly contrasts with scobees_update_gliederung.

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 implies when the tool applies (creating a folder/phase inside an existing Lernpfad or Gliederung), but gives no explicit when-not guidance and does not point to scobees_update_gliederung for modifying existing structures. Usage is inferable rather than stated.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose meaningful post-conditions: the path appears in the school's own library as published but stays INACTIVE until a teacher assigns it to a Lerngruppe in the web UI. That is exactly the kind of side effect an agent cannot infer elsewhere. Remaining gaps are authorization requirements and what the call returns.

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 short sentences, each earning its place: what is created, what to do next, and what state it lands in. The core action is front-loaded in the first clause.

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 7-parameter mutation tool with no annotations and no output schema, the description covers the action, the follow-up workflow and the resulting lifecycle state well. It slightly under-delivers on prerequisites (permissions) and on what the caller gets back, but nothing critical to invoking it correctly is missing.

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 86%, so the schema already documents name, subject_id (with the source tool), jahrgaenge, description, solve_order, stichwoerter and cover_image_path. The description only adds the loose hint that the path lives 'in einem Fach', implying subject_id, and adds no semantics beyond the schema. Baseline 3 is appropriate.

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?

States a specific verb and resource ('Legt einen neuen Lernpfad ... an') and pins the level by calling it the root ('Wurzel') in a subject, which distinguishes it from the sibling tools that add Gliederungen and Aufgaben underneath. An agent can tell exactly what this creates without opening the 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?

Provides explicit workflow ordering: create the root here, then add Gliederungen and Aufgaben 'mit den anderen Werkzeugen', which routes the agent to the sibling tools. It does not explicitly contrast against update_lernpfad or state prerequisites beyond the implicit need for a subject_id, so it stops short of full when/when-not coverage.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the container concept and the intended child-task workflow, but it does not state permissions, side effects, or explicitly clarify that the new ID is returned and needed for subtasks.

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?

Two sentences, front-loaded with the core purpose and followed by the important sequencing instruction. There is no redundant text.

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?

The hierarchy and follow-up workflow are clear, but a create tool with no annotations, no output schema, and incomplete parameter descriptions needs more context. The meaning of parent_id and the return value/ID should be made explicit.

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 50%, and the required parent_id parameter is not explained for this tool. The description adds meaning to mindest_aufgaben via 'Mindestanzahl an Unteraufgaben', but it does not compensate for the undocumented required parent_id or name parameters.

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 the specific action and resource: creating a Wahlpflichtaufgabe. It also explains the resource as a container for subtasks and distinguishes it from scobees_create_aufgabe by describing the parent-child relationship.

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?

It clearly states the follow-up workflow: create the Wahlpflicht container first, then create subtasks with scobees_create_aufgabe using parent_id = this ID. It does not explicitly cover when not to use this tool or compare it with other creation alternatives.

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

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

With no annotations provided, the description carries the full behavioral burden. It does disclose the important cascade behavior ("inkl. Unterelementen!") and the confirm requirement, but omits irreversibility, permission requirements, and what happens if the ID is invalid.

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, front-loaded sentence with the verb first and the cascade warning emphasized. It is efficient, though the exclamation mark is informal and the parenthetical could be integrated more cleanly.

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 destructive tool with no annotations and no output schema, the description covers the key cascade risk and confirm requirement. It still leaves out irreversibility, error behavior, and return semantics, which are important for a delete operation, so it is only minimally adequate.

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 50%: confirm is documented in both schema and description, but id has no description in either. The enumeration of deletable entity types indirectly clarifies what id may refer to, providing some value beyond the schema, but not full compensation for the undocumented id parameter.

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 uses a specific verb ("Löscht") and enumerates exactly which resource types can be deleted (Aufgabe, Gliederung, Wahlpflichtaufgabe, Lernpfad). It is clearly a delete operation, though it does not explicitly contrast itself with the sibling update/create tools.

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 is implied by the verb "Löscht" and the prerequisite "Erfordert confirm=true" is stated, which is useful. However, there is no explicit guidance on when to choose this over sibling tools like scobees_update_* or scobees_move, nor any warning about when not to use it.

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

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

With no annotations present, the description carries the full burden and does disclose the return content (Markdown worksheet, links, attachments), which is the key behavioral trait here. It does not cover failure modes such as a missing/invalid Aufgabe-ID or auth requirements, but for a read operation it gives solid disclosure.

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?

Two compact sentences, zero filler, with what the tool returns front-loaded ahead of the workflow hint. Nothing is redundant with the title.

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?

No output schema exists, so the description must characterize returns — it does so at a high level (Markdown, links, attachments). Between that and the fully documented two-parameter schema, an agent has enough to call it correctly; only edge-case behavior around invalid IDs is unaddressed.

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 100% and both parameters are self-documenting in the schema (Aufgaben-ID with LI-… format, mit_serlo_json flag). The description adds nothing beyond that, so the baseline of 3 applies.

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?

States a specific verb ('Lädt') and resource ('eine einzelne Aufgabe') and enumerates the payload (Arbeitsblatt als Markdown, Links, Anhänge), so the agent knows exactly what comes back. It is clearly distinct from sibling scobees_get_lernpfad by resource, but the description never names an alternative to sharpen the boundary.

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 second sentence ('Für Änderungen an bestehenden Aufgaben') implies a read-before-update workflow, which is a real usage cue. However, it gives no explicit when-not condition and does not point at scobees_update_aufgabe or scobees_create_aufgabe as the follow-up, leaving the routing to inference.

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

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

No annotations exist, so the description carries the whole burden. It does disclose the return shape (a compact tree spanning Gliederungen down to Aufgaben) and that 'Lädt' is a read, but says nothing about permissions, depth/size limits, or behavior on an unknown or inaccessible ID.

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?

Two short sentences, zero filler, with the structural scope front-loaded and the follow-up use case second. Nothing repeats the name or title.

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 one-parameter read tool with no output schema and no annotations, the description covers what is returned (hierarchical tree) and why it matters (IDs for mutations). A brief note on response depth or error cases would close the remaining gap.

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 100% with a single well-documented required parameter ("Lernpfad-ID (LI-…)"), so the schema already does the work. The description adds no format, validation, or sourcing detail beyond referencing that IDs come from the tree.

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?

States a specific verb and resource ("Lädt einen Lernpfad") plus scope ("vollständigem Aufbau (Gliederungen → Aufgaben) als kompakten Baum"), which implicitly separates it from scobees_list_lernpfade and scobees_get_aufgabe. No sibling is named explicitly, so differentiation is inferred rather than declared.

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?

"IDs daraus werden für Änderungen benötigt" gives a concrete workflow cue: call this before update/move/delete operations to obtain the Gliederung and Aufgabe IDs. It never states when NOT to use it or names a competing tool, so it falls short of full routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the returned fields and implies a read-only listing, but says nothing about pagination behaviour (page/page_size exist with defaults), result size limits, or permissions.

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?

Two short sentences with zero waste: the capability and returned fields come first, the usage intent second. Every clause earns its place.

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?

Reasonable for a simple list tool — it names returned fields, compensating for the absent output schema. But with no annotations and half the parameters undocumented, an agent still lacks pagination guidance and confirmation of read-only behaviour.

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 50%: title and subject_id are documented in the schema, and the description reinforces subject scoping ('eines Fachs (oder alle)'). However, page and page_size are undocumented in both places, and no pagination semantics are added — the description does not compensate for the coverage gap.

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?

States a specific verb and resource ('Listet Lernpfade') and adds scope ('eines Fachs (oder alle)') plus the fields returned (ID, Name, Status, Jahrgänge). It is clearly distinguishable from the singular sibling scobees_get_lernpfad, though that sibling is never named.

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?

Provides an explicit usage scenario: 'Zum Finden bestehender Kurse, die erweitert werden sollen' – i.e. discovery before an update. It gives no exclusions or named alternatives (e.g. get_lernpfad for a single item), so it stops short of a 5.

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

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

With no annotations, the description must carry the full burden; it does signal that this is a read/list operation and that filtering is optional rather than required. However, it says nothing about scope (all subjects vs. only those visible to the teacher/workspace), result ordering, or volume, which matters for a picker an agent must act on.

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?

Two short sentences; the core capability and optional filter are front-loaded, and the follow-on sentence earns its place by giving usage context. No filler or redundant restatement of the tool name.

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 one-optional-parameter, non-destructive list tool with no output schema and no nested objects, the description covers what it returns conceptually and how to narrow it. Only the visibility/scope of the returned subjects is left implicit, which is a minor gap at this complexity.

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 100% and the single parameter already documents itself as an optional Lernbereich-ID. The description only restates the optional Lernbereich filtering already present in the schema, adding no format or behavior detail beyond it – the baseline 3 fits.

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?

States a specific verb and resource ("Listet Fächer (Kurse)") plus the optional narrowing dimension (Lernbereich). The resource is clearly distinct from sibling list tools (workspaces, tags, lernpfade), though no sibling is named explicitly as an alternative.

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 second sentence supplies concrete context: this is the picker the teacher uses to choose the subject in which a Lernpfad will be created, which situates it at the start of the create_lernpfad flow. No explicit when-not or exclusions are given, but the usage context is clear.

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

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

No annotations and no output schema, so the description carries the burden. 'Listet' implies a read-only reference lookup, but the description never states the return structure (names, IDs, hierarchy) that a caller needs to pass values into create_lernpfad/create_aufgabe. Adequate but thin for a tool with zero structured behavioral metadata.

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 sentence that front-loads the resource ('Jahrgänge und Differenzierungsstufen der Schule') and closes with the downstream use case. No filler.

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 zero-param reference lookup with no output schema, the description identifies what is returned conceptually and why, but omits how the returned values are keyed (IDs vs labels) and whether results are school-scoped. That is the one piece an agent needs to actually chain this into create_lernpfad.

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?

The tool takes zero parameters, which is the baseline-4 case; there is no argument semantics to explain. Schema coverage is 100% and empty, so nothing is left undocumented.

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 resolves the ambiguous name 'tags' by stating the tool lists Jahrgänge and Differenzierungsstufen of the school, so an agent knows exactly what resource it returns. It doesn't name siblings to distinguish from, but 'list' plus the concrete domain objects make the purpose 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 parenthetical '(für create_lernpfad / create_aufgabe)' explicitly routes the agent: fetch these values before creating a Lernpfad or Aufgabe. That's clear conditional context, though it stops short of stating when-not to use it or naming lookup alternatives like list_subjects.

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

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

With no annotations provided, the description carries the full burden, and it does disclose the key behavioral fact: this is read-only and administrative mutation is out of scope. It says nothing about ordering, completeness, or whether the subjects are returned inline versus by reference, gaps that matter for a zero-parameter listing call.

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?

Two short sentences with zero filler. The resource and its payload (subjects) come first, and the read-only constraint follows as a secondary note, so the agent gets the essential fact immediately.

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 zero-parameter, non-destructive listing tool with no output schema, the description covers what is returned (learning areas together with their subjects) and the permission boundary. Minor shortfall: it never indicates nesting shape or whether the result is exhaustive, which an agent would want before chaining into a get_lernpfad call.

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?

The tool takes no parameters, so the baseline is 4; the schema is empty and there is nothing further the description could reasonably document. The description correctly frames the call as unfiltered and global ("alle Lernbereiche"), which confirms no filtering options are expected.

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?

States a specific verb and resource ("Listet alle Lernbereiche ... mit ihren Fächern"), plus a clarifying gloss ("Kacheln in der Bib") that pins down what a Lernbereich is. It does not, however, distinguish itself from the several sibling list tools (list_subjects, list_tags, list_lernpfade), so the agent must infer the boundary.

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 clause "Nur lesen – Verwaltung bleibt beim Administrator" implies this is a safe read-only discovery call and that write operations live elsewhere, which is useful implied guidance. There is no explicit statement of when to prefer this over scobees_list_subjects or scobees_list_lernpfade, so the alternative selection is left to inference.

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

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

With no annotations, the description still discloses the most important behavioral trait: it does not persist anything, so it is safe to call repeatedly. It does not cover what happens with invalid Markdown, whether output is truncated, or how the generated 'Bausteine' are structured, which matters given no output 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?

One tight sentence with the preview/non-persistence qualifier placed immediately after the action. Nothing extraneous, nothing buried.

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 one-parameter, no-annotation, no-output-schema tool, the description covers the core contract (convert, don't save, return building blocks). It falls short on the return shape and on failure behavior, which the absent output schema leaves entirely to prose.

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% for the single 'markdown' parameter, so the schema offers only 'type: string'. The description mentions Markdown but adds no constraints such as whether full documents or fragments are expected, or which Serlo constructs are supported.

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 gives a concrete verb and resource ('Wandelt Markdown testweise in das Serlo-Format um') plus the preview scope ('ohne etwas zu speichern'). 'Testweise' and 'ohne zu speichern' implicitly separate it from the many create_/update_ siblings, 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 non-persisting preview nature implies the use case (check conversion before committing via scobees_create_aufgabe or similar), but the description never states when to reach for it versus the actual create tools. Usage must be inferred rather than read.

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

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

No annotations are provided, so the description carries the burden alone. 'Zeigt' and 'prüft' convey a read-only, non-mutating operation and name the returned fields, but nothing is said about error behavior on failed authentication or whether the call is idempotent/cached.

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 sentence that front-loads the identity information and appends the authentication check. No redundant restatement of the name or filler.

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?

With no output schema, the description must convey the shape of the result; it names three key fields but not the full payload, and it leaves open what an unauthenticated response looks like. Adequate for a simple tool, but not 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?

The tool takes zero parameters, so there is nothing for the description to document; the baseline for a parameterless tool applies. The description appropriately spends its words on scope and returned fields instead of parameter detail.

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?

States a specific verb and resource: shows the caller's own scobees account and lists the fields returned (ID, Rolle, Schule). It is clearly distinct from the content-oriented siblings (list_lernpfade, create_aufgabe, etc.), though the distinction is implicit rather than called out.

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?

'prüft die Anmeldung' implies a sensible use case — verifying credentials/identity before other calls — but the description never says when to prefer this over alternatives or what to do if the check fails. Usage is inferable but not spelled out.

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

Does 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.

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

With no annotations, the description carries the full burden and does well: it discloses partial-update semantics and warns that arbeitsblatt_markdown/serlo_json completely replace the worksheet, implying destructive overwrite. It still omits permissions, validation behavior for serlo_json, and whether array fields like links/differenzierungen replace or merge.

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?

Two compact sentences with no waste. The core mutation rule is front-loaded, followed immediately by the destructive-replacement warning and prerequisite.

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 mutation tool with 10 parameters, no annotations, and no output schema, the description covers the most important behavioral risk (worksheet replacement) and read-before-write guidance. However, it leaves most parameter semantics undocumented, which is a meaningful gap for an update tool with no schema descriptions.

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 there are 10 parameters, so the description must compensate. It only explains the replacement behavior of arbeitsblatt_markdown and serlo_json and the general partial-update rule; it says nothing about id, the art enum values, links structure, differenzierungen, estimated_time, or interne_notiz.

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?

States a specific verb and resource ('Ändert eine bestehende Aufgabe'), clearly identifying an update operation on an existing task. It does not explicitly contrast with scobees_create_aufgabe, but the update semantics are clear enough to distinguish from create/get siblings.

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?

Explicitly says only provided fields are changed and names scobees_get_aufgabe as a prerequisite before replacing arbeitsblatt_markdown/serlo_json. It gives clear operational guidance, though it does not state when not to use this tool versus create or other update tools.

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

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

No annotations exist, so the description bears the full burden. It does disclose useful behavior beyond the schema: the update is partial ('Name und/oder Beschreibung') and the payload mirrors the create call with an id added. It says nothing about permissions, whether unspecified fields are preserved, error handling, or what is returned, and 'live geprüft' is opaque.

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?

Two short sentences, front-loaded with the action and the affected fields, with no filler prose. The parenthetical 'live geprüft' is the one segment that does not earn its place, being neither verifiable nor actionable for the agent.

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 write tool with no annotations, no output schema, and 0% schema coverage, the description leaves too much open: permitted operations are narrowed to two fields but the behavior for structural moves, empty payloads, and failure cases is unstated. The agent can construct a basic call but cannot predict the outcome.

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 description has to carry parameter meaning. It does name all three parameters implicitly (id, name, Beschreibung), but it calls the field 'Beschreibung' while the schema key is 'description_html' — the agent gets no signal that HTML markup is expected, and id's role is only implied by 'mit id'.

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?

'Ändert Name und/oder Beschreibung einer Gliederungsstruktur' names a specific verb and resource and enumerates the mutable fields. It distinguishes itself from scobees_create_gliederung only obliquely via 'Gleicher Aufruf wie Anlegen, mit id' rather than stating the distinction outright.

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 hint that this is the create call plus an id implies when to reach for it instead of scobees_create_gliederung, but the inference is left to the agent. Nothing says what to do for structural changes (scobees_move) or removals (scobees_delete), nor what to do if neither name nor description is supplied.

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

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

With zero annotations the description carries the full burden and does reasonably well: it discloses patch-style semantics (unspecified fields preserved), identifies in_bib as a publication switch (a meaningful side effect), and flags two operations that must happen elsewhere. It does not state permission requirements, whether publishing to the Bib is reversible, or what the call returns.

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 with the core action front-loaded and the caveats (preserved fields, out-of-scope operations) following. Slightly telegraphic style but no filler.

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 an 8-parameter mutation tool with no annotations and no output schema, the description covers the important gaps: partial-update behavior, the Bib publication side effect, and excluded operations. Missing pieces are secondary – return value, permission prerequisites, and the meaning of the solve_order values.

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 38%, so the description must compensate and largely does: it names all seven optional fields including the mapping of "Reihenfolge" to solve_order and "Titelbild" to cover_image_path, and clarifies in_bib's meaning. It leaves the solve_order enum values (none vs after_solving) and the id parameter's LI-ID format unexplained, so it is not fully compensating.

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?

States a specific verb and resource ("Ändert einen bestehenden Lernpfad") plus the scope qualifier "(Wurzel)", which separates it from scobees_update_gliederung and scobees_create_lernpfad. It then enumerates the exact editable fields, so an agent immediately knows what surface this tool touches.

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?

"Nicht angegebene Felder bleiben erhalten" tells the agent this is a partial update, and "Fach bleibt beim Administrator, Zuweisung an Lerngruppen in der Weboberfläche" explicitly excludes two operations the agent might otherwise attempt. No sibling is named by comparison, so it stops short of a full when/when-not routing statement.

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

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

With no annotations, the description carries the full burden, and it does disclose one important trait: unlisted fields are preserved (partial-merge semantics) rather than overwritten. It says nothing about permissions, whether the id must exist, what happens on invalid values, or what is returned.

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?

Two short sentences, front-loaded with the action and resource, followed by the partial-update rule. No filler.

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 mutation tool with no annotations and no output schema, the description covers the editable field set and merge behavior but omits return value, error behavior, and any auth or permission requirement. Adequate, but there are clear gaps.

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 0%, so the description must compensate, and it does map five of the six parameters to human terms (Name, Beschreibung, Mindestanzahl, Farbe, Titelbild). Only id is left unexplained, and its meaning is self-evident as the required identifier.

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?

States a specific verb (ändert) and resource (Wahlpflichtaufgabe) and enumerates the editable fields. The resource naming separates it from scobees_update_aufgabe and scobees_update_lernpfad, though it does not explicitly reference those siblings for disambiguation.

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?

No conditions for when to use this instead of scobees_update_aufgabe or scobees_update_gliederung, and no prerequisites or permission notes. Usage is only implied by the resource name.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the uploaded image becomes publicly available in the Serlo editor media store and that it returns a URL, but it does not mention authentication requirements, file-size limits, overwrite behavior, or error handling for a write operation with public visibility.

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?

Two front-loaded sentences with no wasted text. The primary purpose and return value come first, followed by the critical storage/privacy note.

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 single-parameter upload tool without an output schema, the description explains the result (a URL for Markdown), accepted formats, storage visibility, and a privacy constraint. It is mostly complete, though an agent would still lack auth and size-limit details.

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 100%, so the `file_path` parameter is already documented. The description adds useful meaning by listing accepted image formats (png/jpg/gif/webp/svg), which constrains what the local path may point to, though it does not clarify path absoluteness or file existence expectations.

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 states a specific verb and resource: it uploads an image for an interactive worksheet and returns the URL for Markdown embedding. It lists supported formats and the intended use, but it does not explicitly distinguish this tool from the sibling `scobees_upload_material`.

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?

It provides clear context for when to use the tool: uploading an image for an interactive worksheet and embedding the returned URL as Markdown. It adds a content exclusion ('keine Personenfotos oder vertraulichen Inhalte') but does not name or compare against alternatives such as `scobees_upload_material`.

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

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

No annotations exist, so the description carries the full burden. It conveys that the file is local (not a URL) and is mutated onto a task, but says nothing about required permissions, whether existing material is replaced or appended, size/type limits, or what is returned on success.

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 front-loaded sentence that leads with the action and target, then enumerates accepted formats. The trailing ellipsis in the type list is slightly loose but no sentence is wasted.

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 three-parameter upload with no output schema and no annotations, the description covers what the tool does, what it targets, and what file kinds are accepted. Gaps remain around return behavior and the image-upload sibling overlap, but nothing essential to invoking it is missing.

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%: only file_path is documented in the schema, and aufgabe_id plus als_musterloesung are bare. The description partially compensates by framing the operation as task-scoped and by explaining the sample-solution mode, but it adds no detail on the ID's format or on when the boolean flag should be set.

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?

States a specific verb and resource: attaches a local file to a task, and explicitly names the two modes (Material vs. Musterlösung) with concrete file-type examples. It stops short of distinguishing itself from the sibling scobees_upload_bild, which also handles images, so an agent cannot fully disambiguate the two.

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 is implied by the enumeration of file types and the two attachment modes, so an agent can infer this is the general-purpose attachment tool. However, no alternative is named and no when-not guidance is given, leaving the overlap with scobees_upload_bild unresolved.

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