Jobroulette

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

Beyond the annotations (non-read-only, idempotent, non-destructive), the description discloses the idempotency consequence ('a second call changes nothing and says so'), the exact error code on the 'ja' path (zustimmung_nur_selbst), and the OAuth scope vermittlung:zustimmen. These are behavioral traits the structured fields 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?

It is front-loaded with the trigger condition and the decision-relevant fact (you cannot accept) appears early. It is slightly dense, with em-dash clauses and an inline scope tag, but every sentence carries 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?

For a two-parameter mutation with an output schema and full annotation coverage, the description covers the trigger, both enum paths, the error case with its code, idempotency, and the auth scope. 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: 'nein' acts on the user's behalf while 'ja' does not mutate and instead fails with a named error. The 'id' parameter is left to the schema's reference to list_employer_introductions, which is adequate.

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 action (respond to an introduction offer, Vermittlungsvorschlag) and explicitly scopes the tool to declining via 'nein'. It does not explicitly distinguish itself from the closest sibling, withdraw_employer_introduction, which is a plausible source of confusion between 'decline an offer' and 'withdraw an introduction', so it falls short of a 5.

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 the triggering situation ('when the user decides on an offer'), gives the per-value behavior for both 'nein' and 'ja', warns that only the first answer counts, and redirects the accept path to the website. That is explicit when/when-not/alternative 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?

Beyond the annotations, the description discloses that the tool creates a draft only, builds recipient/subject/cover letter/resume attachment, refuses the call when no application email exists, and inserts [bitte eintragen] placeholders for missing requirements. These are substantive behavioral details an agent needs before invoking it.

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 trigger is front-loaded and the sentences are information-dense with little waste. It is somewhat long, but most of the length is justified by the draft, placeholder, and refusal behaviors it must convey.

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

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

The description covers the draft workflow, refusal condition, placeholder behavior, attachment handling, and scope, and an output schema exists so return values need not be explained. The main remaining gap is that it does not explicitly route the user to send_job_application for the send step or clarify the stelleId parameter.

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?

There is one required parameter, stelleId, but schema description coverage is 0%. The description refers only to 'that job' and 'matched jobs' and never explicitly explains that stelleId is the UUID of the matched posting to draft against.

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: it drafts an email application for a matched job. It also immediately distinguishes itself from send_job_application by saying 'Sends nothing', so an agent can tell which sibling to select.

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 a clear trigger: use when the user wants to apply for one of their matched jobs. It also says to show the draft for editing and signing, but it does not explicitly name send_job_application as the follow-up tool for actually sending.

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 readOnly/idempotent/non-destructive, so the description carries the real burden and does: no recalculation, persistence across resume edits, `erneuerbarAb` marking when refresh becomes possible, `zustand` = `verschwunden` handling with next-day removal, and the required scope cv:lesen. This is behavior an agent cannot infer from any structured field.

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?

Opens with the trigger, then the return shape, then staleness, then the edge-case instruction, then scope — a front-loaded order with no filler. Every sentence changes what the agent does next.

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 enumerated, yet the description goes further and explains how to act on the fields (`verschwunden`, `erneuerbarAb`). Combined with the auth scope and staleness rules, 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The doc-string-style field references (`erneuerbarAb`, `zustand`) are return-value semantics rather than parameter 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?

Names a specific verb+resource (show the five jobs currently matched to the resume) and immediately scopes it as stored results rather than recomputed ones, which is exactly what distinguishes it from refresh_job_matches. An agent can pick it over the sibling 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 trigger ('when the user asks for jobs (Stellen) that fit them or wants to see their job matches again') and names the alternative path ('the selection stays until the user replaces it with refresh_job_matches'). It also states a when-not rule: do not offer to apply to a `verschwunden` job.

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/idempotent/non-destructive, so the safety profile is covered. The description adds value beyond that by disclosing the returned content and the required scope ('cv:lesen'), which is a real authorization constraint an agent should know. It omits pagination/volume and default filtering behavior, 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?

Three tight sentences: trigger first, then returned content, then scope. No restatement of the name or filler, and the most decision-relevant information is front-loaded.

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, annotations cover the safety profile, and the single parameter is fully documented in schema. The description supplies the trigger and scope constraint, leaving no meaningful gap for correct invocation.

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 nurOffene is fully documented there (default true, false also returns answered offers). The description never mentions the open/answered distinction, so it adds nothing 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 (list/return) and resource (introduction offers, Vermittlung) and enumerates the returned fields: employer, job, and when the user was asked. This clearly separates it from siblings like answer_employer_introduction or withdraw_employer_introduction, which act on a single 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: 'Use this when the user asks whether Jobroulette wants to introduce them to an employer for a job.' That is a real when-to-use condition rather than an implied one. It does not explicitly route to siblings (e.g. use answer_employer_introduction to respond), so it stops short of 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so no safety burden remains. The description adds genuinely non-obvious context: the required scope 'cv:lesen' and a domain caveat that 'angenommen' means in transit rather than delivered — a real correctness aid the schema 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 the usage trigger, then return content, then scope; every clause carries information. The middle clause ('to whom, when, with which attachment and how far delivery has got') is slightly dense and runs on, but it is not padding.

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 shape need not be explained, and the description still summarizes the returned fields plus the status semantics. The one remaining gap is behavior on an empty list or how many applications are returned, which is minor for a zero-argument list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly implies a full unfiltered listing rather than leaving the agent wondering about required inputs.

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 ... job applications (Bewerbungen)') and scopes it to applications 'they have sent', which distinguishes it from siblings like draft_job_application or send_job_application. An agent can route to this tool from the name and first sentence 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 an explicit trigger ('when the user asks about the job applications they have sent'), which is the key selection signal versus the send/draft/withdraw siblings. It does not explicitly name alternatives (e.g. 'to send a new one use send_job_application'), so it falls just short of the 5 bar.

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?

While annotations declare it is destructive and not read-only, the description adds critical temporal behavioral traits. It dictates a 24-hour cooldown and specifies the exact string used for refusal ('zu_frueh'), providing crucial operational details beyond standard structural hints.

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 definition is tightly written. It logically flows from the use case requirement to the operational behavior (frequency limit and error handling) and finally defines the functional scope. Every sentence provides a necessary constraint or piece of logic.

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 the complexity of the operation (state replacement) and the lack of parameters, the description is maximally complete. It defines the scope (cv:schreiben), the outcome (5 new jobs), and the operational boundaries (24-hour limit), providing the agent with all necessary information to call it safely and 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?

The input schema contains zero parameters, making parameter semantics moot. Given the 100% schema description coverage, a baseline score of 4 is warranted as the description adds essential contextual limits (frequency/scope) despite having no parameters to define.

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 is highly specific, using the verb 'Replaces' and defining the resource clearly ('up to five jobs'). It differentiates itself from standard job retrieval tools by specifying that it replaces the *current* matches with *new* ones, which is crucial for an agent to differentiate from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides extremely granular usage guidelines, stating it should 'Use this only when the user explicitly asks for new or different jobs.' Furthermore, it imposes a hard temporal constraint ('Once every 24 hours') and defines the specific error response for violation.

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 beyond the annotations by explaining the actual idempotency semantics ('A second call for the same job sends nothing and names the first application') and by disclosing the required auth scope (bewerbung:senden) and consent framing. What it doesn't cover is failure behavior or what an omitted attachment defaults to beyond 'the user's resume', which keeps it from 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?

Front-loaded with the trigger condition and generally tight, but 'explicitly wants it sent' and 'explicitly asked to send it' restate the same consent rule twice, which is mild redundancy rather than 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 an irreversible outbound-email mutation, the description supplies the consent gate, the idempotent-repeat behavior, the auth scope, and the attachment payload — and an output schema already covers return values. Nothing an agent needs to call this 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 description coverage is 0%, so the description must carry the load. It does clarify anschreiben (cover letter) and anhang (resume document or another PDF), but stelleId is never explained (presumably the job from get_job_matches) and the optionality of anhang is only implied.

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 ('Sends exactly one email to the employer') plus the payload (cover letter + resume/PDF attachment). It is clearly distinguished from the sibling draft_job_application by the 'sent vs. draft' framing, so an agent can pick correctly without opening a 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 precondition ('after they have seen the draft and explicitly asked to send it'), which doubles as a when-not rule: don't call while the draft is unseen or unsent-requested. It also names the consequence-based stop condition for repeat calls, leaving little 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 explains that the first call only reads except that a PDF overwrites the stored document (explaining why destructiveHint=true), that saving twice updates idempotently and yields no new matches, that matches appear only on first save, and that a call fails with einwilligung_fehlt before consent. These are real behavioral traits the agent cannot infer from structured fields.

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 triggering condition and dense with non-redundant information, but it is a long, unstructured block of prose mixing English and German tokens that could be easier to scan. Every sentence earns its place, but organization could be tighter.

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, nested, mutating tool with consent gating, it covers the flow, error state, destructive PDF behavior, idempotency, and the imZuschnitt mismatch warning. With an output schema present, return-shape explanation is rightly omitted, and nothing an agent needs to call 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?

Although schema coverage is 100%, the description adds constraints not present in the schema: 'Exactly one of freitext, pdf, felder per call' (mutual exclusivity across otherwise all-optional params), wunsch only valid with felder, and what each input is read vs saved for. This meaningfully exceeds the schema 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?

States a specific verb+resource (read and save the user's one resume/CV) and explicitly frames the two-step read-then-save flow. It even distinguishes itself from sibling tools, naming refresh_job_matches as the source of new matches, so an agent can tell what this tool does and does not do 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 triggers ('user is looking for a job and shares their resume... or wants to change the one on file'), explicit sequencing (first freitext/pdf, then felder), explicit prohibitions ('Never save fields the user has not seen'), and explicit alternative (refresh_job_matches). Even the consent precondition and its failure behavior are documented.

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: the time window during which the withdraw is effective, the shift of data responsibility to the employer afterward, explicit failure behavior ('fails and says so'), and the required scope (vermittlung:zustimmen). The 'second call changes nothing' line reinforces idempotentHint rather than contradicting it.

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 sentences, front-loaded with the use case and followed by the edge-case condition and scope. Dense but every sentence carries actionable 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, and the description still pre-empts the key failure mode so the agent knows what to expect on error. For a single-parameter mutation with a clear permission scope, nothing essential 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?

Only one parameter, and the schema already documents it fully (100% coverage), including a pointer to list_employer_introductions as the source of the id. The description adds no further parameter detail, 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 (withdraw/take back) and resource (consent to employer introduction), with the German synonym for disambiguation. It is clearly distinct from sibling tools like answer_employer_introduction and list_employer_introductions.

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 trigger ('when the user wants to take back their consent') and a when-not boundary ('works until Jobroulette has presented the user; after that... this tool fails'). It does not name a specific sibling as the alternative, but the temporal condition is decisive enough to select the tool correctly.

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