JobJump

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

Annotations already declare readOnly, idempotent and closed-world, so the description doesn't need to argue safety; instead it adds genuinely new context: the calculation is deterministic from the passed values, the figures are approximate, and it enumerates what it explicitly does not model (Lohnsteuerjahresausgleich, one-off payments, company pensions, capital income, tax-card allowances). It also discloses the legal mechanics of the employer subsidy. Minor gap: nothing about the data source's update cadence or error behaviour for out-of-range input.

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 correctly: purpose, when to use, and result shape come first, then parameter guidance, then scope limits. Some sentences partly restate schema text (the 8/9 percent church-tax split, the Kinderfreibetrag explanation) and the line about sharing an engine with JobJump's civil-servant calculator adds little decision value, but overall each paragraph is topical and no sentence 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?

For a 14-parameter financial calculator with an output schema, the description covers everything an agent needs: when to call it, how to elicit each non-obvious parameter from the user, special handling for private insurance and Beamte, and the boundaries of the model. Return values need no explanation because the output schema exists, yet the description still summarises the breakdown usefully.

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 a 3; the description earns above that by adding operational meaning beyond the schema — tax_class is 'the single largest driver' and should be asked for rather than guessed, classes 3/5 imply married and 6 a second job, bundesland drives both church tax and the Saxony care split, and child_allowances is a 0.5-step allowance count, not a child count. The private-insurance paragraphs explain how the two premium parameters interact (care premium omitted means the health premium counts as health cover only), which the schema states but the description reinforces in workflow terms.

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 with scope pinned down: German take-home pay from gross for the 2026 tax year, using the official 2026 wage-tax program plus statutory social-insurance rates. It also names what the result contains (wage tax, solidarity surcharge, church tax, each insurance contribution), which clearly separates it from gross-pay siblings like get_tariff_pay and from evaluate_salary_offer.

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: 'when the user gives a gross salary and wants to know what arrives in their account, or wants to compare two offers net.' It also clarifies the division of labour with get_tariff_pay ('returns the gross pay for a civil-servant grade'), i.e. feed gross in here. It stops short of explicitly ruling out evaluate_salary_offer, so the sibling set is not fully disambiguated.

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 safety (readOnly, idempotent, non-destructive), yet the description still adds real behavioral detail: the 8 percent threshold bands, the 16-city factor and its fallback to national figures, the response contents (corridor, negotiation range), and the gross-only / aggregate-data caveat. The one gap is that it doesn't state how ambiguous job titles are resolved when no benchmark match exists.

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 tight paragraphs: what it does, how the comparison works, and what it does not do. Front-loaded and every sentence carries information, though the mention of JobJump's website appears twice and could be trimmed.

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 enumerate return fields, yet it still previews the corridor and negotiation range and explains the threshold bands. Combined with the explicit scope limits (gross only, not contract advice), an agent has everything needed to call it 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 coverage is 100%, so baseline is 3, but the description adds meaning by explaining how parameters feed the comparison: search_region only adjusts via a city factor for 16 cities and otherwise falls back nationally, and seniority should be passed 'when the user said it' rather than guessed. It largely repeats schema content on period multiplication and normalisation.

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 first sentence states a specific verb, resource and scope ('judge whether a gross salary offer in Germany is below, in or above the market') and ties it to a concrete reference point. It is clearly distinguishable from get_salary_benchmark (returns figures) and calculate_net_salary (net pay).

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 names the triggering situation explicitly: the user names an offer amount and asks whether it is fair, low, good, or how much to negotiate. It also routes the agent elsewhere for the adjacent need ('call calculate_net_salary with the offered amount for net pay').

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 read-only/idempotent/closed-world, yet the description adds real behavioral context: unknown slug returns NOT_FOUND, coverage limited to Germany, null-with-note instead of guessing, provenance in `sources`, and explicit marking of pay as employer-stated vs JobJump estimate, plus the `recruiter` meaning and a prompt-injection warning about embedded employer text.

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 compact paragraphs organized as what-it-returns, when-to-use/how-to-get-the-slug, then data-provenance caveats – front-loaded and scannable. It is dense rather than wasteful, though the slug guidance is largely mirrored in the schema and the provenance paragraph is a bit long.

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 re-explained; the description instead explains the semantics that the schema cannot (source attribution, null-with-note policy, estimate vs stated pay, recruiter flag), and covers the one input's sourcing and failure mode. Nothing needed 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 coverage is 100% and already documents the slug pattern and NOT_FOUND. The description still adds value by showing two concrete derivation routes (employer_slug from get_top_employers, or the bei- segment of a jobjump.net/jobs URL) with examples, which the schema states only in compressed form.

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 ('Get one employer's profile') and enumerates exactly what is returned: headquarters, size, website, description, and posting aggregates (count, cities, titles, pay). This is clearly distinguishable from siblings get_top_employers (ranking list), search_jobs (posting search) and get_job (single posting).

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 ('when the user asks about a specific employer') with concrete example questions, and routes to the alternatives: get_top_employers with an occupation to discover a slug, search_jobs with `employer` set to list postings. It also states a negative condition: never guess a slug.

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 (which already cover readOnly/idempotent/no-destructive), the description discloses that only published postings resolve, that expired or merged postings error rather than returning stale data, that the employer text is wrapped in untrusted-text markers and must not be followed as instructions, and enumerates fields deliberately withheld (application URL, contacts, coordinates, billing). That is unusually rich behavioral context for a read 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?

Three short paragraphs, front-loaded with purpose then usage then trust/scope caveats — each earns its place. Minor redundancy: the summary/full 1200-character distinction is stated here and again in the schema description for `detail`.

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 structure needn't be explained; the description instead covers what an agent cannot infer from structured fields — the not-found behavior on expired postings, the untrusted-content boundary, and the deliberately omitted fields. Nothing needed to call this 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 baseline is 3 and the schema already documents both parameters in detail. The description adds modestly on top: it clarifies that job_id accepts either the UUID from a search result or the full slug from a jobjump.net/jobs/ URL, and gives the token-cost rationale behind the summary default, though the detail enum semantics largely restate 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 and resource ('Fetch the full detail of one job posting on JobJump') plus the addressing key (stable id or slug). It clearly separates itself from search_jobs by naming it as the prerequisite step rather than a substitute.

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 names the sequencing ('Use this after search_jobs when the user wants the responsibilities, requirements, benefits or deadline of a specific posting') and gives a decision rule for the detail level based on user intent and token cost. It also states which postings are out of scope (expired or merged return not-found).

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: explains the two non-comparable data sources and why they must not be merged, gives freshness/lag per series (monthly official lagging weeks, weekly stock, daily flow), documents the degraded-success path (covered city with no official series returns JobJump data with a note, not an error), notes that listing only extras skips the series, and flags third-party text from job fairs as quote-only, never instructions.

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 data caveats, then extras — a sensible order for a read tool. It is long and the paragraph describing `job_fairs`/`offices`/`nearby_cities` largely repeats the schema's `include` description, which is the main wasted 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 four-parameter read tool with a full schema, complete annotations and an output schema, the description supplies the one thing structured fields cannot: how to interpret and keep separate the two data sources. Interpretation cautions, coverage limits and the extras-gating rule are all present.

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, and the description earns the step up by explaining server-side resolution of `search_region` to one of ~250 cities (accepting aliases like 'Cologne') and warning that it is a search criterion, not the caller's location. `days` and `months` are left entirely to the schema, which is acceptable given full coverage.

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 — report the labour-market situation for one German city or all of Germany — and names exactly what comes back (official statistics plus JobJump posting counts). No sibling tool competes on this axis, and the geographic scope is stated up front.

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 concrete triggering questions ('how the job market looks somewhere', 'whether a region is hiring', 'how unemployment there has moved') and an explicit exclusion ('Regions outside Germany are not covered'). It does not point to any alternative tool, but none of the listed salary/job siblings overlaps, so the guidance is effectively complete.

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 (which already declare read-only, idempotent, closed-world), the description discloses normalization rules, result cardinalities (up to 30 siblings, up to 5 aliases), the fact that failure is a success with `resolved: null`, and which content is deliberately omitted (no salary figures, profile excludes pay sentences and FAQs). That is substantive behavioral context an agent could not infer from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and the paragraph on sibling-tool routing is genuinely load-bearing. Some sentences duplicate the schema's `include` descriptions and the output schema's field list, which is minor redundancy in an otherwise well-organized 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?

An agent knows when to pick this tool, what to pass, what the result shape contains, what happens on no match, and where to go for pay or postings. With an output schema present, the description need not explain return values, yet the brief naming of returned fields aids selection without bloating.

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 nevertheless adds intent-level guidance — 'ask only for what the user needs', the note that both sections are general editorial content, and the explicit reminder that the profile excludes pay. It largely restates what the schema already says for `include`, so it does not go far beyond the baseline.

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 names a specific verb pair (map, optionally describe) and a specific resource (job title → JobJump occupation), including the normalization step. It is clearly distinguishable from siblings such as search_jobs, get_salary_benchmark and get_tariff_pay, which are explicitly named as separate concerns.

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 concrete triggering conditions (unusual, colloquial, English or gendered wording; questions about what the job involves or how to write a CV) and explicit exclusions routed to alternatives ('call get_salary_benchmark or search_jobs', 'get_tariff_pay for public-sector pay'). It also covers the failure path, telling the agent to ask for another wording when `resolved` is null.

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 a safe read-only, idempotent, closed-world operation. The description goes well beyond that by disclosing mixed units (annual vs monthly gross), the absence of true min/max/percentiles, the Germany-wide full-time-only scope, the fact that search_region changes no figure, the ~65-occupation coverage limit, and the exclusion of tax/individual/employer data.

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 the key alternative, then organized by concern. It is long, but most sentences prevent concrete misuse (unit mixing, expecting regional figures). A few points overlap the schema, keeping it short of a perfect score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists and annotations cover safety, the description supplies everything else an agent needs: data provenance, unit pitfalls, regional and coverage limits, and scope exclusions. 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 description coverage is 100%, so the schema already documents every parameter including the seniority enum bands, the search_region caveat, and include_official_series. The description largely repeats this schema content (job_title in user's own words, seniority bands, search_region not applied) rather than adding new parameter-level meaning, 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 and resource ('look up what an occupation pays in Germany') and names the two data sources combined. It explicitly distinguishes itself from siblings by naming evaluate_salary_offer for judging an offer and calculate_net_salary for net pay.

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 ('user asks what a role pays or how pay differs by seniority') and when-not-to-use with the named alternative ('to judge a specific offer, use evaluate_salary_offer instead'). Also routes net-pay questions to calculate_net_salary.

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 read-only/idempotent/no-destruction, but the description adds substantive domain behavior: amounts are gross base pay for full-time work, family supplements, allowances and overtime are excluded, and the figures are reproduced from published tables set by the agreement parties or by law. It also states the default-year behavior and the discovery-then-refetch pattern for occupations.

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 paragraphs that front-load what the tool does and then move to invocation and output caveats; nearly every sentence carries new information. Minor redundancy between the opening and the second paragraph's restatement of agreement/grade/step, but not enough to hurt scanning.

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 lookup tool with five optional parameters and an output schema, this covers everything an agent needs: what to pass, what comes back (monthly gross, annual figure, validity dates, full step ladder, step intervals), what is deliberately excluded from the figures, and where to go for net pay. 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?

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the interaction between parameters that the schema does not encode — agreement+grade together, step optional to get the full grade ladder, or occupation as a substitute for both. It stops short of explaining step syntax or year-range semantics that the schema already covers.

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 verb and resource ('look up German public-sector pay') and enumerates the exact table families covered: collective agreements for public, church and welfare employers, plus statutory Besoldung for the federation and each state. It is clearly separable from siblings such as get_salary_benchmark and calculate_net_salary, which the description itself routes to.

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 triggers ('when the user names a pay table with a grade... or asks which pay table applies to their occupation') and the conditional branch: pass agreement+grade directly, or pass occupation first and call again. It also names the alternative for a different need ('For take-home pay call calculate_net_salary... set employment to civil_servant').

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond that: counts are today's open postings rather than company size, the list is ordered by count only, unresolvable places degrade to all of Germany with a note, unmatched occupations return an empty list with a note, and employer names must be treated as data not instructions. A minor gap is that the German-only coverage is stated but nothing about rate limits or result truncation beyond `limit`.

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 trigger conditions, then parameters, then return shape, which is a sensible order. It is longer than strictly necessary — the enumeration of returned fields (name, count, kind, page, logo, slug) partially duplicates the output schema and could be trimmed, though the `kind`/`recruiter` explanation 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?

For a 4-parameter read tool with a full output schema and rich annotations, nothing an agent needs is missing: trigger conditions, Germany-only coverage, degradation behavior, ordering semantics, the follow-up call using `employer_slug`, and an injection warning on employer names are all present.

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 baseline is 3; the description nonetheless adds semantics the schema lacks — pass the occupation as a German job title, gendered forms normalize, and `search_region` is a search filter that must never be inferred from device context. The radius default/max is only implicit ('default 25 km, at most 50 km'), which keeps 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?

States a specific verb and resource ('list the employers with the most open postings for an occupation') plus the scope (Germany-only, radius around a place). It is clearly separable from search_jobs (which lists postings) and get_employer (single employer lookup), so an agent can route 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?

Explicit trigger conditions ('when the user asks who is hiring for a role...') plus an explicit prohibition ('Do not infer search_region from device or client context') and a hand-off rule: to see an employer's postings, call search_jobs with `employer` set to the returned slug. Alternatives and follow-ups are named concretely.

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 the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for what they don't say: Germany-only coverage, recency-and-match ordering that is not influenced by employer payments, no sponsorship fields, cursor lifetime of 15 minutes, a 100-record paging cap, and cursor invalidation when filters change. Only minor gap is that it doesn't describe error modes beyond NOT_FOUND.

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?

Five paragraphs, which is long relative to most tool-usage blocks. To its credit the scope sentence, the usage sentence, and the paging rules are front-loaded, and each paragraph carries a distinct piece of information. It could be trimmed, though, for example the ranking and sponsorship sentence and part of the return-shape paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there are 12 parameters, a rich output schema, and 3 enums, the description still works as a complete brief: it covers scope, required-filter rule, parameter handling rules, localization constraint, the results contract, and paging limits. An agent could call this tool correctly without reading anything else.

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 baseline is 3, but the description adds real semantics beyond the schema: pass the user's own words for query, never infer search_region from device or client context, never pass coordinates or addresses, and reuse next_cursor unchanged with identical filters. Those are non-obvious usage constraints the schema does not state.

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 (search live job postings on JobJump, a German job board) plus the dimensions it filters on: occupation, region, work mode, contract type. The description names its sibling (get_job) for full advert text and get_top_employers for employer slugs, so an agent can tell the tools apart from the description alone.

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 conditions (finding open positions, or counting postings for a role in a place), an explicit constraint (at least one of query/search_region/category/employer is required because an unfiltered scan is not useful), and explicit routing to get_top_employers for the employer slug and get_job for full text. It also warns that an unknown slug returns NOT_FOUND.

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