Read-only search across current job listings on stellenonline.de (German job portal).
Scored across 3 tools
count_jobs (filtered count) and get_total_jobs (unfiltered total) both return a single number, so an agent could occasionally confuse them, but the descriptions clearly distinguish filtered vs. unfiltered. search_jobs is clearly distinct as the full-result retrieval tool.
All three tools follow a consistent snake_case verb_noun pattern (count_jobs, get_total_jobs, search_jobs). The convention is predictable and readable throughout.
Three tools is on the lean side for a job search API, but each has a distinct role (search, filtered count, total count). count_jobs and get_total_jobs are arguably a slight overlap that could be merged, but the count is defensible.
The surface covers the core read-only workflow: search jobs, count matches with filters, and check total index size. The main gap is a get_job_by_id tool for fetching a single job's details, though search results already include the key fields.
Count how many jobs match a search without returning full results. Returns structured JSON.
Use this when the user asks "how many jobs..." (in any language), including salary-constrained counts like "how many jobs pay at least 60k?" or "how many jobs advertise a salary at all?" (use has_salary=True).
Args: q: Search keywords, e.g. "Softwareentwickler Python" location: City or region, e.g. "München", "Bodensee" working_plan: "Vollzeit", "Teilzeit", "Homeoffice", or "Minijob" job_offer_type: "Arbeitsplatz", "Ausbildung", "Praktikum", "Freiberuflich", "Werkstudent", "Trainee", "Duales-Studium" min_salary: Minimum ANNUAL gross salary in EUR (optional), e.g. 60000. Filtered server-side with the same semantics as search_jobs: monthly/hourly amounts are normalised to a yearly figure first, and salary ranges match on overlap. A job with range 30.000–45.000 € is counted at min_salary=40000 (ranges overlap). max_salary: Maximum annual gross salary in EUR (optional, same semantics). A job with range 30.000–45.000 € is NOT counted at max_salary=25000. has_salary: If True, count only jobs that advertise a salary at all (regardless of amount). If False, count only jobs WITHOUT a salary. Leave unset to ignore. Use this for "how many jobs have a salary?"; combine with min_salary/max_salary as needed.
Returns: On success: {"count": int, "filters": {"q": str|null, "location": str|null, "working_plan": str|null, "job_offer_type": str|null, "min_salary": float|null, "max_salary": float|null, "has_salary": bool|null}} On error: {"error": str}
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| location | No | ||
| has_salary | No | ||
| max_salary | No | ||
| min_salary | No | ||
| working_plan | No | ||
| job_offer_type | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive and closed-world hints, and the description still adds real value: server-side salary normalisation of monthly/hourly to annual, range-overlap matching rules with worked examples (30.000–45.000 counted at 40k, not at 25k), and the has_salary unset/true/false trichotomy.
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 and usage, then organises Args and Returns into scannable sections that earn their space given the undocumented schema. The standalone line "Returns structured JSON." is redundant with the detailed Returns block that follows, a minor bit of waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter, zero-required, zero-schema-coverage tool, the description supplies everything needed to call it correctly, including filter semantics and error shape. An output schema exists, so the Returns block is arguably surplus but harmless.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the entire burden and does: all seven parameters are documented with types, expected values and regional examples (München, Vollzeit, Arbeitsplatz). The salary overlap semantics and has_salary behaviour go well beyond what the bare anyOf schema conveys.
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: counting jobs matching a search, explicitly without returning full results. It distinguishes itself functionally from search_jobs by mentioning shared salary semantics, but never contrasts itself with the sibling get_total_jobs, which an agent could easily confuse with a filtered count.
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 invocation triggers ("how many jobs..." in any language) plus concrete salary-count phrasings and the has_salary=True case. It does not spell out the inverse condition (use search_jobs when full results are needed), though "without returning full results" implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the total number of jobs in the database (no filters). Returns structured JSON.
Returns the complete job count. Use this to check the overall index size.
Returns: On success: {"total_jobs": int} On error: {"error": str}
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds the success/error response shapes, but those are largely duplicated by the declared output schema, and it says nothing about cost, caching, or freshness of the count.
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 statement is front-loaded and short, but the second sentence ('Returns the complete job count') restates the first, and the Returns block duplicates an output schema that the agent already receives. Roughly a third of the text does not earn 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?
With zero parameters, full annotations, and an output schema, the description covers everything needed to invoke the tool correctly except sibling disambiguation against count_jobs. That remaining gap is the only meaningful omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate — the baseline of 4 applies. Stating '(no filters)' correctly confirms that all filtering semantics live in sibling tools.
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 the total number of jobs') and adds the scoping qualifier '(no filters)', which hints at differentiation from filtered counting. However, it never names the sibling count_jobs, so an agent must infer which of the two count-oriented tools to pick.
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?
'Use this to check the overall index size' gives one legitimate use case, but there is no guidance on when to prefer this over count_jobs or search_jobs, and no exclusions. Usage is implied rather than routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for jobs in the STON job database. Returns structured JSON.
Call this tool ONCE per user request, then present the returned jobs list
to the user in whatever format fits (markdown list, table, plain text).
Always include the apply link from the url field for each job.
If has_more is true, mention total_found and ask whether to fetch more.
NEVER call this tool multiple times in a row to collect all pages automatically.
To count results without fetching full job data, prefer count_jobs. If a
filter you need isn't on count_jobs, call this tool with rows=1 and read
total_found (the count is server-side and independent of rows).
Args: q: Search keywords (German job market — examples: "Softwareentwickler Python", "Krankenpfleger") location: City, region or area, e.g. "München", "Ravensburg", "Bodensee", "Baden-Württemberg" radius: Search radius in km around the location, e.g. 25, 50 (default: server setting) working_plan: One of: "Vollzeit", "Teilzeit", "Minijob", "Homeoffice" (comma-separated for multiple) job_offer_type: One of: "Arbeitsplatz", "Ausbildung", "Praktikum", "Freiberuflich", "Werkstudent", "Trainee", "Duales-Studium" (comma-separated for multiple) min_salary: Minimum ANNUAL gross salary in EUR (optional), e.g. 60000. Filtered server-side. Jobs advertised per month/hour are normalised to a yearly figure first, so e.g. 5000/month matches min_salary=60000. Salary ranges match on OVERLAP, not containment: a job advertised as 30.000–45.000 € IS returned at min_salary=40000 (the ranges overlap), and is NOT returned at max_salary=25000. max_salary: Maximum annual gross salary in EUR (optional, same overlap semantics) has_salary: If True, return only jobs that advertise a salary at all (any amount); if False, only jobs without one. Leave unset to ignore. sort: "relevance" (default) or "date" (newest first) page: Page number starting at 1 rows: Results per page, 1-50 (default: 25)
Returns: On success: { "total_found": int, "page": int, "rows": int, "total_pages": int, "has_more": bool, "salary_filter": null | {"min_salary": float|null, "max_salary": float|null}, "jobs": [ { "id": str, "title": str, "company_name": str, "location": str, "date": str (ISO-8601), "url": str, "salary": null | {"annual_eur": float, "monthly_eur": float, "currency": str, "min_annual_eur"?: float, "max_annual_eur"?: float, "data_quality"?: "suspect"} # implausibly high → likely a data error }, ... ] } On error: {"error": str}
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| page | No | ||
| rows | No | ||
| sort | No | ||
| radius | No | ||
| location | No | ||
| has_salary | No | ||
| max_salary | No | ||
| min_salary | No | ||
| working_plan | No | ||
| job_offer_type | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld=false, and the description goes well beyond them: server-side counting independent of rows, salary normalization from monthly/hourly to annual, overlap (not containment) matching semantics, the 'suspect' data_quality flag, and the error shape. This is rich behavioral context an agent could not infer.
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 behavioral rules, and nearly every sentence earns its place. The 'Returns:' block substantially duplicates the existing output schema, which is mild redundancy, but the salary and data_quality annotations within it add 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?
For an 11-parameter search tool with an output schema, the description covers invocation rules, filtering semantics, pagination contract, and error handling. Nothing an agent needs to call it correctly or interpret results 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 0%, so the description carries the full burden and does so: it enumerates all 11 parameters, gives German-market examples for q/location, enumerates valid values for working_plan and job_offer_type, defines salary units and overlap semantics, and states page/rows bounds and defaults.
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 for jobs in the STON job database') plus the return format. It explicitly distinguishes itself from the sibling count_jobs and gives a fallback pattern for counting, so an agent can route correctly 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 when-to-use and when-not-to-use: call once per request, never auto-paginate, prefer count_jobs for counting, and use rows=1 with total_found as the fallback. It also prescribes presentation behavior (include the apply url, mention total_found when has_more).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
count_jobsget_total_jobssearch_jobsSearch public procurement notices from 17 sources across Germany, the EU and the UK. Read-only.
Search and retrieve job postings on Intermediair (read-only).
Search active job listings, salaries and employers in Norway (kollegia.no). Read-only, no login.
Search and retrieve job postings on Nationale Vacaturebank, the largest Dutch jobs site (read-only).
Add one secure layer between your agents and this server.
