Stellen-Radar

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context on top: nothing is persisted, only supplied fields change while omitted ones keep their profile value, and the returned kennung expires after 60 minutes. It also discloses what the result contains per channel and under which inputs the target-area metric is computed.

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?

Front-loaded with the verb and the no-persist guarantee, then the save path, then the fallback sibling. Every sentence carries information, though the run-on clause listing the returned metrics is denser than it needs to be.

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 14-parameter preview tool with an output schema, this covers everything an agent needs: what it does, what does not get saved, the downstream save step with token validity, the sibling for the no-profile case, and a sketch of the returned metrics. No material gap remains.

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%, so the schema carries the field-level meaning and a 3 would be the floor. The description adds the non-obvious semantics the schema cannot: partial-update behavior (omitted fields unchanged) and the fact that ziel_begriffe/ziel_branchen do not filter but measure how many desired positions rank at the top.

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?

Names a specific action (dry-run computation of a change to one's own profile) plus the concrete output: hits before/after per channel, new and dropped positions, and target-area ranking. It explicitly positions itself against the two closest siblings (aenderung_uebernehmen for saving, stellen_finden for stats without a profile), so an agent can distinguish it without opening any 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 an explicit prescription ('Nutze dies vor jeder Profiländerung'), the exact follow-up step and required artifact ('gespeichert wird erst mit aenderung_uebernehmen und der kennung aus der Antwort'), and a when-not case ('Für Eckdaten ohne gespeichertes Profil nimm stellen_finden'). Both the alternative and the condition selecting it are stated outright.

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?

Very strong beyond annotations: it enumerates which fields are overwritten, which are preserved (Name, Kurzbeschreibung), the full-access requirement, a 60-minute single-use token, and that there is no undo with the only recovery being to recompute and re-apply. The one gap is the single-use kennung sitting unreconciled with idempotentHint=true — a retry does not re-apply but does fail, and the description never says what the agent should expect on a repeat 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?

Front-loaded with the action and its overwrite scope, then usage condition, then access/limits, then the no-undo warning — a logical order with no filler sentences. The enumerated field lists make it dense, but each item carries real information an agent needs.

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?

Destructive mutation with a returned output schema; the description covers the destructive scope, prerequisites, authorization level, token lifetime, and irreversibility. Nothing essential for a correct invocation 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 100%, so the baseline is 3; the description adds consequence-level meaning by stating the kennung is time- and use-limited and that ralf_vorschlag numbers get marked as accepted after the call. It could still have clarified behaviour when kennung is expired or already consumed.

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?

A specific verb (speichern/übernehmen) on a specific resource (die durchgerechnete Änderung im Profil), with the exact set of fields affected named. It is clearly distinguished from the sibling aenderung_durchrechnen, which computes rather than persists.

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?

Explicit precondition: only call after aenderung_durchrechnen has produced a kennung and the person has confirmed the computed change. It also names the optional path (ralf_vorschlag referencing ralf_vorschlaege from profil_lesen), so the agent knows when the parameter applies.

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?

Annotations declare openWorldHint=true, readOnlyHint=false and destructiveHint=false, so the write/external nature is already signaled. The description adds meaningful context beyond that: the agent will reply by email to the account address (a visible side effect) and that the call requires explicit user request and confirmation. It does not discuss rate limits or what happens on repeated calls.

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?

Front-loaded with purpose and recipient, followed by scope, exclusions and the consent rule; every sentence carries information. The long semicolon-chained middle sentence is dense but not redundant.

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 annotations covering the safety profile and an output schema covering the return value, the description supplies everything else an agent needs: what triggers the call, what must not trigger it, the alternative tool, and the required user confirmation.

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%, so all three parameters (including the enum values for kategorie and the structured-content guidance for anliegen) are already documented in the schema. The description only reinforces the feedback routing, which is already in the kategorie description, 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 concrete verb+resource ('Ein Anliegen an den Support ... übergeben') and names the concrete recipient (Ralf, KI-Support-Agent) plus the response channel (E-Mail an die Kontoadresse). It is immediately distinguishable from siblings like feedback_geben or the profile 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?

Gives explicit use cases (Konto, Abo, Zahlung, Lebenslauf, Unterlagen, technische Fehler), explicit exclusions (Profil und Stellen-Agent steuern die anderen Werkzeuge direkt), names the alternative for feedback (feedback_geben) and adds a consent precondition: nur auf Wunsch des Nutzers und nach Bestätigung.

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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, and the description reinforces this with 'Speichert nichts' plus the account requirement ('Verlangt ein verbundenes Konto'). It also discloses non-obvious response behavior: when no profile exists the answer carries profil_anlegen_mit, and each hit adds punktzahl, gemerkt and beworben. It stops short of describing pagination or the 5-result limit for non-full access, which the schema covers instead.

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 routing decision and the when-to-use rule are front-loaded, and every clause carries information (alternatives, account requirement, no persistence, response extras). Mild redundancy remains in listing the card fields (Titel, Ort, Arbeitgeber...), which an output schema already covers.

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 10-parameter search with full schema coverage and an output schema, the description supplies the missing pieces an agent needs: when to pick it, the auth prerequisite, side-effect-free behavior, and a hint that the response may route back to profile creation. Remaining gaps (result cap / pagination behavior) are documented in the schema, not needed here.

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 every parameter carries a detailed German description, including matching weights (Funktion > Branche, Titel am stärksten). The prose adds essentially no parameter guidance beyond the returned punktzahl/merkt fields, 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 concrete verb and resource — zeigt die besten passenden Stellen zu Eckdaten einer Person als Karte, nach Passung sortiert — and enumerates the fields each card carries. It explicitly distinguishes itself from stellen_finden (numbers) and treffer_abrufen (saved profile), so an agent can pick it out from the sibling list without opening any 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 an explicit when-to-use condition ('die Person will die Stellen selbst sehen und kein gespeichertes Profil') plus two named alternatives with the condition that selects each. It also states the prerequisite of a connected account, which is the kind of precondition an agent must check before calling.

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?

Annotations already declare this is a non-read-only, non-idempotent, closed-world write. The description adds real context beyond that: the feedback lands with a team that reads every entry, and crucially there is no email reply. That 'no reply' expectation is exactly the kind of behavioral detail an agent needs before invoking.

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?

Front-loads purpose, then behavior ('keine Antwort per E-Mail'), then routing to alternatives — a logical order with no filler. It is on the longer side for a two-parameter tool, but each clause carries routing or expectation-setting value.

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 annotations covering the safety profile, an output schema present, and full schema description coverage, the description only needs to add behavioral and routing context — which it does completely. An agent has everything required to select and invoke this tool correctly.

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 (art enum, text with length bounds) are fully documented in the schema. The description only loosely echoes the enum values (Lob, Kritik, Wünsche, Ideen), so it adds little beyond structured data — baseline 3.

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 (Feedback/Verbesserungsvorschläge zum Stellen-Radar weitergeben) and enumerates the kinds of content it carries (Lob, Kritik, Wünsche, Ideen). It also explicitly distinguishes itself from sibling tools by naming an_support_uebergeben, stelle_merken, stelle_ausblenden and stelle_melden.

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 when-to-use condition ('auf Wunsch der Person für Rückmeldungen ohne Antwortwunsch') and an explicit when-not with the correct alternative ('Braucht sie Hilfe oder eine Antwort ... nimm an_support_uebergeben'). Per-job signals are routed to three named siblings, leaving nothing 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?

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds substantive behavior: results are numbers only (no individual postings, no map), values are rounded on the website as 'über X', newly-discovered is a 7-day window with trend versus earlier days, and the counted region must be stated explicitly in the answer.

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, densely packed sentence with no filler and the core purpose front-loaded. Readability suffers slightly from three levels of nested parentheses around the output-field names, but every clause carries 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?

An output schema exists, so return values need not be explained, yet the description still maps the key fields (kanal_bezeichnung, zaehlung, je_kanal_summen.personaldienstleister). Combined with scope, default, exclusions and the sibling alternative, nothing needed to invoke 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 100% and the enum for gebiet already documents Germany as default and DACH as the exception. The description adds only the instruction to name the gebiet field in the response, which is marginal 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+resource+scope: counts of active jobs across the whole market, without title or location, defaulting to Germany. It explicitly contrasts itself with stellen_finden, so an agent can separate the two 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?

Gives an explicit routing rule: use this for general job-market questions or comparisons; for a specific position or region use stellen_finden, whose channels are directly comparable. Both the when and the alternative are named.

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?

Annotations already establish that this is a non-readOnly, non-destructive, non-idempotent mutation. The description adds important behavior beyond the annotations: profile-limit counting, refusal at the maximum, the first automatic profile not counting toward the limit, and the first profile setting up the weekly job agent.

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 action is front-loaded and most details are relevant to correct invocation. However, the profile-limit, first-profile, and agent-setup nuances make the paragraph dense and somewhat run-on.

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 complex 14-parameter mutation with an output schema, annotations, and full schema coverage, the description supplies the missing operational context: alternatives, profile-limit behavior, automatic-mode constraints, and the first-profile side effect.

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%, so all 14 parameters are already documented in the schema. The description reinforces the automatisch=true condition and profile-limit context, but it does not add substantial parameter-level meaning beyond what the schema already provides.

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 states a specific verb and resource: 'Legt ein neues Suchprofil im Konto an.' It also distinguishes creation from changing an existing profile and from deletion, so an agent can identify the correct operation 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?

It gives explicit when-to-use guidance: when the person wants an additional profile or when an answer from profil_anlegen_mit contains one, with automatisch=true. It also names the alternatives for modifying an existing profile and for undoing creation.

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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered; 'Nur lesen' merely restates it. The description adds a genuinely useful behavioral trait not in the annotations: the result is capped at 10 profiles, implying no full enumeration or pagination. It stops short of saying what happens on truncation or ordering, so not a 5.

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?

Purpose and the 10-cap are front-loaded, then routing to siblings, then the read-only note. Three tight sentences with no filler; the field enumeration is compact and informative rather than redundant.

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 0-param read tool with full annotations, an output schema, and no nested objects, the description supplies everything needed: scope, the cap, and routing to the two related tools. Return-value detail is handled by the output schema, so no gap remains.

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?

Zero parameters and additionalProperties=false, so there is nothing for the description to disambiguate; this is the baseline for a parameterless tool. The description correctly adds no parameter commentary, keeping it aligned with the empty 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 (listet) and resource (eigene Suchprofile im Stellen-Radar), and enumerates the returned fields (profil_id, Name, Kurzbeschreibung, Trefferzahl, Stand des Stellen-Agenten). It explicitly distinguishes itself from profil_lesen and treffer_abrufen, so an agent can route without opening any 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 explicit when-to-use ('für einen Überblick oder um die profil_id für andere Werkzeuge zu finden') and names both alternatives with the condition that selects each: profil_lesen for a profile's search fields, treffer_abrufen for the hits themselves. Nothing 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?

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description still adds real context beyond them: the returned data includes open suggestions from Ralf (ralf_vorschlaege) and deliberately omits the CV text, which tells the agent what it can and cannot surface to the user.

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 action is front-loaded in the first clause, and the field enumeration, usage triggers and alternatives each add distinct value with no filler. The long comma-separated field list makes the sentence heavy, but every item is informative rather than redundant.

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 read tool with a full annotation set and an output schema, the description covers everything an agent needs: what is returned, what is withheld, when to call it, and which siblings to use otherwise. Nothing material is left to inference.

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 single profil_id parameter is fully documented in the schema (100% coverage) including the hint that it comes from profile_auflisten. The description adds no syntax, format or constraint information about the parameter, so the schema carries the full load — baseline 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?

"Liest alle Suchfelder eines eigenen Profils" names a specific verb and resource, then enumerates exactly which fields are returned (Zielpositionen, Funktionen, Branchen, ..., Kurzbeschreibung) and what is excluded (ohne Lebenslauf-Text). It also explicitly distinguishes itself from profile_auflisten and aenderung_durchrechnen, so an agent can pick it without opening any 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 three concrete trigger conditions: before discussing a change, when the person asks what their profile searches for, and when adopting Ralf's suggestions (with an example utterance). It also names the two sibling tools to use instead for listing profiles and for measuring a change.

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?

Annotations carry destructiveHint=true, but the description adds context annotations cannot: a 30-day recovery window, that the response returns a sicherung_id usable with profil_wiederherstellen, and the explicit-confirmation precondition. This is substantive behavioral disclosure beyond the structured safety flags.

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?

Front-loads the destructive action, then the backup/recovery consequence, then the alternative routing. No filler; every clause conveys actionable information for calling it correctly.

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?

An output schema exists, so return format need not be spelled out, yet the description still flags the key return field (sicherung_id) and the recovery path. Nothing an agent needs to call this destructive tool safely 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 100%, so both parameters (profil_id, bestaetigt) are fully documented in the schema. The description reinforces the confirmation requirement but adds no format or syntactic detail beyond what the schema already provides, so the baseline 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 precise verb (Löscht) and resource (ein eigenes Profil samt Stellen-Agent), and distinguishes itself from siblings by naming what it does not cover. An agent can identify this as the destructive profile-deletion 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 explicit when-to-use ('nur nach ausdrücklicher Bestätigung der Person') and routes adjacent intents to alternatives: stellen_agent_einstellen with an=false to stop mails, aenderung_durchrechnen to change search fields. This is textbook when/when-not/alternatives 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?

Annotations already declare readOnlyHint=false and idempotentHint=true, but the description adds genuinely new context: the 30-day backup retention window and the fact that a repeat call with the same sicherung_id is a no-op. It does not spell out the failure behavior once the backup has expired, which is the remaining gap.

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, front-loaded with the core action and retention limit, then usage guidance, then the idempotency caveat. Every sentence carries distinct 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?

With one fully-documented parameter, an output schema, and annotations covering the safety profile, the description supplies everything else an agent needs: source of the deletion, time window, and repeat-call 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 description coverage is 100%, and the schema already explains that sicherung_id comes from the profil_loeschen response with an example value. The description adds no further parameter detail, so the baseline 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+resource (restore a deleted profile from backup) and ties it to the producing tool profil_loeschen. It also explicitly names what it is not (profil_anlegen for new profiles), so an agent can distinguish it from siblings without opening schemas.

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 triggering condition ('Nutze dies, wenn die Person ein gelöschtes Profil wiederhaben will') and routes the alternative case to profil_anlegen. The 30-day backup window also implicitly states when the tool is no longer applicable.

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?

Annotations only declare destructive=true, idempotent=true and non-readOnly. The description goes well beyond that: no reason required, effect limited to this account/profile, the posting itself is unchanged, an existing bookmark is lifted, and the action is explicitly reversible via rueckgaengig=true. That is exactly the extra context a mutation tool needs.

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?

Front-loaded with the core action and its reversibility, then routing guidance. Dense but nearly every clause carries meaning; only the reversal note mildly duplicates the schema.

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 annotations covering safety, an output schema handling return values, and full schema coverage of parameters, the description supplies the remaining gaps: reversibility, account/profile scope, and sibling routing. Nothing an agent needs to call 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 100%, so all four parameters are already documented in the schema, including rueckgaengig and profil_id scoping. The description restates the reversal flag but adds no syntax or format information beyond the schema, 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 precise verb and resource ('Blendet eine Stelle aus der eigenen Trefferliste aus') and immediately scopes the effect to the account and to the listing's bookmark state. It is clearly distinguishable from the related siblings it names.

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 explicit when-to-use ('Nutze dies, wenn die Stelle für die Person nicht passt') and routes to two named alternatives with their own selection conditions: stelle_melden for offline/filled/misclassified listings and stelle_merken for bookmarking.

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?

Annotations already declare mutation (readOnlyHint=false), idempotency and non-destructiveness, but the description adds real context beyond that: it 'sets only the marker, sends nothing', that applied positions flow into recommendations like saved ones, and that it is reversible via rueckgaengig=true. This side-effect and reversibility disclosure is exactly the kind of value structured fields don't carry.

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?

Four tight sentences, front-loaded with purpose, then side effects, usage routing and reversibility. Every sentence earns its place, though the 'wie der Koffer im Stellen-Radar' metaphor is decorative rather than informative.

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 an output schema present, return values need not be explained, and the description covers side effects, routing to alternatives and reversal. It is complete enough for correct invocation; only parameter syntax is left entirely to the schema.

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 all four parameters are already documented in the schema, giving a baseline of 3. The description only restates the reversal behavior of rueckgaengig and adds no new syntax or format meaning beyond what the schema already provides.

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: 'Markiert eine Stelle im angegebenen Profil als beworben.' It also distinguishes itself from siblings by naming stelle_merken and stelle_notiz_anhaengen, so an agent can route without opening other schemas.

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 trigger ('wenn die Person sagt, dass sie sich beworben hat') and names the alternatives with their selecting conditions ('für bloßes Interesse nimm stelle_merken, für Einzelheiten ... stelle_notiz_anhaengen'). The when-to-use branch is fully specified, not implied.

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?

Beyond the annotations, the description explains what is returned, including keywords and a summary capped at 1,000 characters, that it is not the ad text, and that tasks/requirements only appear in the original ad. It also discloses that profil_id adds saved/applied status and note metadata, with note state available even for expired postings where active is false.

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 description is front-loaded with the tool's purpose, then usage guidance, then supplementary profil_id behavior. It is two focused paragraphs, though slightly long and repeats some profil_id details already present in the schema.

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 an output schema present, the description need not explain return formatting, and it still covers purpose, usage alternatives, data inclusions, limitations, and profil_id effects. Nothing an agent needs to select or invoke this read-only detail tool 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 coverage is 100%, so the schema already documents quelle, stelle_id, and profil_id. The description adds meaning by explaining the concrete effect of passing profil_id, including saved/applied status and note timestamp metadata, which goes beyond the schema's brief description.

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/resource: it returns features of a single job posting, the original ad link, keywords, and a short summary. It explicitly distinguishes itself from sibling tools by naming treffer_abrufen for result overviews and trefferliste_laden for loading many jobs.

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 states exactly when to use the tool: when a person wants more about a specific job or needs the current note state before stelle_notiz_ersetzen. It also explicitly routes the agent to alternatives for other needs: treffer_abrufen for overviews and trefferliste_laden for many jobs.

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?

Goes well beyond the annotations: it explains the review pipeline ('Das Stellen-Radar prüft die Meldung, erst eine bestätigte ändert die Stelle'), the immediate per-account side effect for two of the four types, and that the action cannot be undone. Destructive/irreversible nature is confirmed and elaborated rather than merely restated.

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?

Front-loaded with purpose, then side effects, then the alternative and the irreversibility warning — each sentence carries a distinct decision-relevant fact. Slightly dense in the middle clause, but nothing is redundant.

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 annotations, a 100%-covered schema and an output schema present, the description supplies the remaining decision-critical context: what happens after filing, when the listing disappears, and that the write is final. Nothing an agent needs before calling 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 100%, so the baseline is 3, but the description adds cross-cutting semantics the schema only states per-field: the requirement that a report carry a real 'Beleg' and that a mere guess is insufficient, which governs beleg, art and the conditional merkmal/vorschlag/partner fields together.

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 ('Meldet einen Datenfehler an einer Stelle') and enumerates the four reportable defect types, so the agent knows exactly what class of action this is. It also names the confusable sibling stelle_ausblenden, which sharpens 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?

Gives an explicit precondition ('nur mit klarem Beleg, nicht aus Vermutung') and an explicit routing rule to an alternative ('Passt die Stelle der Person nur nicht, nimm stelle_ausblenden'). Both when-to-use and when-not-to-use are covered.

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?

Annotations cover the safety profile (non-readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: saved jobs flow into recommendations and an earlier Ausblenden of the same posting is lifted, plus reversibility via rueckgaengig=true. This side effect would not be predictable from the annotations alone.

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?

Front-loaded with the action and its effect before the routing guidance. The single dense paragraph is a little long, but every clause (effect, trigger, three alternatives, reversibility) carries information and none is 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?

Output schema exists, so return values need no explanation. Given a 4-parameter mutation tool, the description covers trigger, alternatives, side effects and reversibility — everything an agent needs to call it correctly in context.

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%, so all four parameters are already documented by the schema, including quelle, stelle_id sourcing and the profiling scope of profil_id. The description only restates the rueckgaengig=true reversal switch, adding no syntax or format detail beyond the schema, 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 and resource ('Merkt eine Stelle') and immediately explains the effect: saved jobs feed the recommendation engine and a prior hide is lifted. An agent can distinguish this from stelle_beworben, stelle_ausblenden and stelle_notiz_anhaengen without opening any 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?

Explicit trigger condition ('Nutze dies, wenn die Person eine Stelle interessant findet') plus three named alternatives each paired with the condition that selects it (applied → stelle_beworben, unsuitable → stelle_ausblenden, own note → stelle_notiz_anhaengen). Nothing 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?

Beyond the annotations (readOnly=false, destructive=true, idempotent=true), it concretely explains what gets destroyed ('Abschalten entfernt ihn'), that an existing agent is overwritten with the new frequency, and the delivery constraint that without trial/subscription mail arrives only on Sundays even with 'täglich'. That is exactly the kind of consequence and prerequisite detail annotations cannot convey.

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?

Front-loaded with purpose, then effect, then overwrite/removal semantics, then the Sunday-mail constraint, and finally the consent rule and alternative. Dense but each sentence carries information; only the Sunday caveat is slightly redundant with the schema 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?

For a 3-parameter mutation tool with an output schema and full annotation coverage, the description supplies everything an agent needs: purpose, consequences, consent precondition, frequency semantics and the correct sibling for read-only viewing.

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%, so the schema already documents an, profil_id and haeufigkeit, including the 'täglich nur mit vollem Zugang, sonst sonntags' caveat. The description restates that limitation and otherwise adds no syntax or format detail beyond the schema, 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?

It states a specific verb set (einrichten, ändern, abschalten) on a specific resource (Stellen-Agent eines Profils) and explains the observable effect (user receives matching jobs by email). It also names the sibling treffer_abrufen for merely viewing matches, so an agent can separate this tool from its neighbors.

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?

Explicit when-to-use and consent requirements: 'Nur aufrufen, wenn der Nutzer es ausdrücklich möchte; vorher Profil und Häufigkeit nennen und bestätigen lassen.' It also gives the alternative ('Zum Ansehen von Treffern stattdessen treffer_abrufen'), covering when-not.

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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial non-schema behavior: it stores nothing, the response includes profil_anlegen_mit when no profile exists, vergleich_bundesweit is omitted when counting takes too long (a latency-dependent shape), and each hit carries punktzahl plus gemerkt/beworben for saved profiles. These are operational traits an agent cannot derive from annotations or the output schema alone.

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?

Purpose, scope constraint, sibling routing and output shape are front-loaded in the first two paragraphs, and nearly every clause carries information. It is longer than ideal: the dangling fragment 'Je Treffer zusätzlich punktzahl … gemerkt und beworben' interrupts the flow, and the closing measurement paragraph re-states routing already implied earlier.

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 9-parameter read tool with an output schema, the description covers the remaining unknowns: the umkreis_km default behavior, the missing-bundesweit-value case, the no-profile fallback in the response, and where the personnel-service aggregate lives. Nothing an agent needs to call this correctly or interpret the result 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 100%, so the baseline is 3; the description still earns above that by clarifying the decisive edge case that 'ohne umkreis_km sucht stellen_finden bundesweit, auch wenn ein Ort genannt ist' — resolving the interaction between ort and umkreis_km that the per-field schema text leaves ambiguous. It also names the aggregate output path je_kanal_summen.personaldienstleister, which is parameter-adjacent result semantics.

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 opening sentence gives a specific verb and resource ('Zählt die passenden Stellen im Stellen-Radar zu strukturierten Eckdaten einer Person') and immediately disambiguates against siblings by naming marktlage, beste_treffer_zeigen, treffer_abrufen and marktlage's no-title/no-location scope. It also states what the result contains (gesamt, je Kanal, gut passend, neu in 7 Tagen, fünf beste Treffer), so an agent knows exactly what class of operation this is.

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?

Explicit routing: 'Für mehr Treffer zu denselben Eckdaten nimm beste_treffer_zeigen, für ein gespeichertes Profil treffer_abrufen, für den Gesamtmarkt ohne Titel und Ort marktlage', plus the measurement path via aenderung_durchrechnen for stored profiles versus re-calling stellen_finden for ad-hoc criteria. Each alternative is paired with the condition that selects it, leaving nothing 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?

Adds substantial context beyond the annotations: existing text is left untouched, the note spans all account profiles, is visible only to the person, and the 4,000-character limit causes rejection rather than truncation. This is exactly the mutation semantics annotations don't convey.

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?

Front-loads the core action, then layers constraints, visibility, and the sibling pointer. Every sentence carries distinct information with no redundancy.

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?

An output schema exists, so return values need not be described. For a write tool the description covers behavior, limits, visibility, idempotency implications, and the alternative tool — nothing an agent needs 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 100%, so all three parameters are already documented, including the maxLength=4000 that the description restates. The description adds no parameter-specific meaning beyond the schema, so the baseline 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?

Specific verb (ergänzt/anhängen) plus resource (eigene Notiz zu einer Stelle) with explicit scope. It names the sibling stelle_notiz_ersetzen as the tool for the opposite operation, so an agent can distinguish them without opening schemas.

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?

States exactly when this tool applies (append an entry dated today, create the note if none exists) and explicitly routes the alternative case — rewriting or deleting — to stelle_notiz_ersetzen. Nothing 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?

Goes well beyond the annotations: it discloses optimistic-concurrency behavior (stale stand means nothing is overwritten and the response returns the current text), a 4,000-character cap, and an undocumented side effect (the new text is auto-prefixed with today's date unless it already starts with one). It also clarifies that empty text deletes, which sharpens the destructiveHint=true annotation into concrete semantics.

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?

Front-loads the core action and consequence, then layers preconditions, conflict behavior, and the alternative in a single dense but waste-free block. Every clause carries information an agent needs to call the tool correctly; no boilerplate.

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, non-idempotent mutation with four required parameters, the description covers preconditions, overwrite protection, limits, side effects, and the sibling alternative. An output schema exists and the one return detail that matters (current text on conflict) is still called out, so nothing needed for correct invocation 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 100%, so the baseline is 3, but the description adds real meaning: the empty-text deletion behavior of 'text', the origin and conflict consequence of 'stand' (including the 'neu' special case), and confirmation of the length cap. Much of this overlaps the schema property descriptions, so it falls short of 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?

States a specific verb and resource ('Ersetzt die eigene Notiz ... zu einer Stelle') plus the full scope of the operation, including that empty text deletes the note. It explicitly names the sibling it is not (stelle_notiz_anhaengen), so an agent can distinguish replace from append 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?

Gives explicit when-to-use ('Nutze dies, um eine Notiz umzuschreiben oder zu löschen') and names the alternative with its selecting condition ('zum Ergänzen nimm stelle_notiz_anhaengen, das den bestehenden Text behält'). The precondition (stand from stelle_im_detail, or "neu") is spelled out as a hard requirement.

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?

Annotations already cover readOnly/idempotent/destructive/openWorld, so the description goes beyond by disclosing that hidden jobs are excluded, that per-match punktzahl, gemerkt and beworben fields are returned, and that channel counts and a 'remaining' number accompany the list. It doesn't detail pagination or the access-limited 5-result cap beyond what the schema says.

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?

Front-loads what the tool returns and then the alternatives, with every sentence carrying information. Structure is slightly hurt by stray indentation/whitespace artifacts and a fairly long third paragraph, but there is no redundant 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 read-only retrieval tool with an output schema (so return values needn't be explained) and rich annotations, the description covers purpose, alternatives, exclusions and the follow-up measurement path. Nothing an agent needs to call 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 100%, so the schema already documents anzahl, profil_id and stellen_anzeigen fully. The description only indirectly references the 25 cap ('mehr als 25 Treffer'); it adds no format or default detail beyond the schema, so baseline 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+resource: retrieving the matches of a saved own profile, best first, mirroring the Stellen-Radar list. It explicitly names the sibling tools it is not (beste_treffer_zeigen, trefferliste_laden, stelle_im_detail) so an agent can route without opening schemas.

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 explicit when-to-use and when-to-use-alternatives: Eckdaten ohne Profil -> beste_treffer_zeigen, Filtern/Vergleichen/>25 Treffer -> trefferliste_laden, Einzelstelle -> stelle_im_detail. It also routes measurement questions to aenderung_durchrechnen or stellen_finden depending on whether a profile exists.

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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavioral context: the 100-hit cap, that rows carry shortened summaries and notes (full text only in stelle_im_detail), that recommendations are interleaved without rank or score, and that page 1 exposes notizen_ohne_zeile for dropped postings. It does not cover rate limits or how staleness via 'stand' is reported, so not a 5.

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?

Purpose and alternatives are front-loaded, but the text is long and dense, and the second paragraph enumerates row fields that the output schema already defines. warum_weniger is explained twice (description and schema) and there are line-break artifacts ('bis zu den 100\nbesten Treffern'), so it is informative but not tight.

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 5-parameter, paginated, mode-switching read tool with an output schema, the description covers when to call it, alternatives, pagination state threading, and the special ordering of recommendations. The row-level enumeration is largely redundant with the output schema, but nothing essential for correct invocation 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 100% and already documents each parameter well, so the baseline is 3; the description adds the pagination protocol (ab_rang and stand come from the previous response) and signals that warum_weniger is a mode switch that decomposes filter causes rather than a listing option. stellen_anzeigen's 'nur bei ausdrücklichem Wunsch' guidance is also reinforced, though no extra syntax is added.

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 die Trefferliste eines eigenen Profils als Tabelle') plus scope: up to 100 hits, paginated by ab_rang, summaries instead of full ads, no map. It explicitly names the siblings it is not (treffer_abrufen for display, stelle_im_detail for a single job), so an agent can choose without opening schemas.

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 a concrete usage trigger ('wenn die Person mit ihrer Liste ... arbeiten will: sichten, filtern, sortieren, vergleichen, auswählen') and names two alternatives with their distinct conditions. It also routes a specific sub-case ('warum sie in der App nur wenige Treffer sieht') to the warum_weniger flag, and explains page continuation via naechster_rang/stand.

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