Ocean of Jobs

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

Goes well beyond the annotations: discloses a hard cap ("Up to 5 alerts per account"), a non-obvious email-routing quirk ("the address the account had when the token was made"), and an auth requirement. The annotations only say this is a non-idempotent, non-destructive write; the description supplies the constraints and consequences that actually shape a correct 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?

Four short sentences, each carrying distinct information — behavior, cap, email routing, permission gating. The core purpose is front-loaded and 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?

An output schema exists so return values need no explanation, and the description still covers the things the schema cannot: account limit, token scope, email destination, and the consent gate. 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% and every filter field is documented in the schema with examples, so the schema carries the parameter burden. The description only refers to "the filter" generically and adds no matching semantics (e.g. how multiple fields combine) beyond what the schema states.

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 opens with a specific verb and resource ("Create a job alert") and immediately explains what the artifact does: emails matching new jobs on the user's preference schedule. It is clearly distinct from list_alerts/update_alert/delete_alert by verb alone, though no sibling is named explicitly.

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

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

"Create one only when the user asks for it" is an explicit when-to-use constraint backed by a prerequisite ("Needs the user's personal access token"). It does not name alternatives for editing an existing alert, but the gating guidance is concrete rather than 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?

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful behavioral context beyond those annotations by stating the practical effect ('Its emails stop') and the authentication requirement ('Needs the user's personal access token').

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 three short sentences, front-loaded with the action, followed by the effect and auth requirement. Every sentence adds relevant information without 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 simple one-parameter destructive tool, the description covers the action, consequence, and authentication need. The annotations cover safety and idempotency, the schema covers the id parameter, and an output schema exists, so no critical context 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?

There is one parameter with 100% schema description coverage, and the schema explains that the id comes from list_alerts. The description does not add parameter-specific detail, so the baseline score of 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?

The description names a specific verb and resource: delete a job alert. It is easy to distinguish from siblings like create_alert, update_alert, and list_alerts because the destructive action is explicit.

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

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

Usage is implied by the destructive verb, and the description notes that deleting stops emails. However, it does not explicitly say when to delete versus update or disable an alert, nor does it warn when not to use this tool.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds a summary of returned data (open job counts, new jobs this week, tracking duration, newest jobs, page), which is somewhat redundant with the output schema and does not disclose auth, rate limits, or error behavior.

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 a single sentence that front-loads the resource and lookup keys, then lists the returned data efficiently. It is appropriately sized, though the return-field list is somewhat dense.

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 values, yet it gives a useful summary. It covers the lookup key and general purpose for a low-complexity, single-parameter tool, though it lacks usage guidance against sibling tools.

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

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

Schema coverage is 100% and the schema already describes the single 'company' parameter with examples (Wix, wix.com). The description restates 'by name or domain' without adding format, validation, or disambiguation details beyond 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?

The description names the specific resource (a company on Ocean of Jobs) and the lookup keys (name or domain), and enumerates what the tool returns. It does not explicitly differentiate from the job-oriented siblings get_job and search_jobs, but the resource noun makes the distinction clear.

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

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

The description provides no when-to-use guidance, no prerequisites, and no mention of alternatives or exclusions. It simply describes what the tool returns, leaving the agent to infer the appropriate context.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that the result includes verification against the employer's ATS and link ordering, but since an output schema exists this return-content detail is largely redundant.

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

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

A single dense sentence that front-loads the resource and scope; the enumeration of returned fields is a bit run-on 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?

For a single-parameter read tool with an output schema and full annotation coverage, the definition is nearly self-sufficient; the only minor gap is that return-value details duplicate the output 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 the id format is already documented. The description goes beyond the schema by stating the provenance of the id (from search_jobs or get_company), which is genuinely useful for constructing the call.

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 ('One job on Ocean of Jobs by its id') and names the siblings that supply the id (search_jobs, get_company), so an agent can distinguish it from those tools without inspecting 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?

It clearly routes the agent by naming where the required id comes from (search_jobs or get_company), which implies this tool is the follow-up step. It lacks an explicit 'do not use this for searching' exclusion, but the context is unambiguous.

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, and non-destructive, so the description rightly doesn't repeat those. It does add a genuinely useful operational fact beyond the structured fields: the call requires the user's personal access token, an auth requirement the schema does not express.

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 payload contents and ending with the auth constraint. Slight awkwardness in 'the seniority, workplace and places they want' keeps it from being maximally clean, but there is no filler.

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

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

With an output schema documenting return values, no parameters, and annotations covering the safety profile, the description only needs to add purpose, consumers, and auth — and it does all three. Only the relationship to update_preferences is left implicit.

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 the baseline of 4 applies; there is nothing parameter-wise the description needs to compensate for.

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 enumerates exactly what the tool returns (skills, seniority, workplace, places, alert email timing), which is more specific than the title alone. It doesn't use an explicit verb like 'retrieve' and doesn't name update_preferences as its write counterpart, so the read/write split is only implied by context.

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 who consumes the preferences ('the board's best matches and the account overview use them'), which hints at when an agent would want this data. There is no explicit when-to-use/when-not guidance and no mention of the sibling update_preferences for the mutation case.

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 behavior, so the bar is lower; the description still adds real value by disclosing the personal-access-token requirement and by explaining the shape of each record (saved search, filter, on/off state). It stops short of noting ordering or whether disabled alerts are included.

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

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

A single front-loaded sentence with no filler: resource identity first, record shape second, auth requirement last. 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 structure need not be spelled out, and the description still summarizes the payload fields and the auth prerequisite. Missing only minor operational details such as ordering or whether the list is paginated.

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, so the baseline is 4; there is nothing about the input contract the schema leaves ambiguous. The description correctly implies the scope is implicitly the token's owner rather than a parameterized user.

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 the resource precisely and defines it ("a saved search whose new matches are emailed" plus its filter and enabled state), so an agent knows exactly what a returned item is. It does not explicitly contrast with siblings like list_saved_jobs or the create/update/delete_alert triad, though the 'list' verb plus resource definition makes the distinction mostly inferable.

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

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

Usage is implied by the verb: read the user's alerts, presumably before update_alert or delete_alert. There is no explicit when-to-use, no exclusion of list_saved_jobs/list_auto_apply_queue, and no statement that this is the entry point for alert IDs needed by siblings.

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 safety, and the description adds value beyond them: the personal-access-token requirement, the newest-first ordering, and precise semantics for each status value including the prohibition on conflating unconfirmed/sent with submitted. That is exactly the behavioral context an agent cannot derive 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-loads the purpose in the first clause and then spends words only on the status/outcome distinctions, which carry real disambiguation value. Slightly dense with repeated 'never call X submitted' phrasing that could be tightened, but nothing is wasted.

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

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

Output schema exists so return shape needn't be explained, and the description still supplies the semantic meanings of status and outcome codes plus auth needs. The only gap is the absence of any pointer to list_auto_apply_queue for the queue-vs-history distinction.

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 limit parameter (1-25, default 10) is fully documented there. The description adds nothing about limit, 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 (jobs the extension worked on for the user) plus the ordering (newest first) and the fields returned (status, source, outcome). It doesn't explicitly contrast with list_auto_apply_queue, so an agent must infer that this is history versus pending queue.

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

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

Usage is only implied by 'the jobs the extension worked on' – past tense suggests completed attempts rather than queued ones. No explicit when-to-use or when-not-to-use, and no sibling tool is named even though list_auto_apply_queue is the obvious alternative.

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 and non-destructive, but the description adds real context: the ordering guarantee, the queue lifecycle (an item disappears after the extension attempts it), and the authentication requirement. It does not cover pagination or what happens when the queue is empty, but the added value is clear.

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

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

Three short sentences, each earning its place: what is returned, the lifecycle rule, and the auth prerequisite. Content is front-loaded with no repetition of the title or annotations.

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 fields, and it correctly gestures at them ("same fields as search results") instead of enumerating. Combined with the ordering, lifecycle and auth notes, the only minor gap is pagination/empty-queue behavior for a read-only list.

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 a single optional parameter with 100% schema coverage including the 1–25 range and a default of 10, so the schema fully carries this dimension. The description adds nothing about limit or truncation behavior, which is the correct baseline for a fully documented 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?

"The jobs waiting in the user's auto apply queue" names a specific resource and adds ordering (oldest first), so the agent knows exactly what comes back. The distinction from list_auto_apply_history is only implied by "waiting in the queue" and "leaves the queue once the extension has tried it" rather than stated, so it stops short of full sibling differentiation.

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

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

Usage is implied by "waiting in the queue" — read this for pending items, history for attempted ones — but neither list_auto_apply_history nor queue_for_auto_apply is named, and there is no explicit when-to-use or when-not framing.

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 (readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=false). The description adds useful behavioral context beyond annotations: the ordering ('newest saved first'), the returned fields ('same fields as search results and when each was saved'), and the authentication requirement ('Needs the user's personal access token').

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 two sentences and contains no obvious waste. It is reasonably front-loaded, though starting with 'The jobs saved...' rather than a direct verb phrase makes the purpose slightly less immediate than it could 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 simple read-only list tool with an output schema, annotations covering safety, and a fully documented parameter schema, the description provides the key extra context an agent needs: authentication requirement, ordering, and return-field expectations. It leaves no critical calling detail 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 input schema has 100% description coverage for the single 'limit' parameter, fully documenting its range and default. The description adds no parameter-specific syntax or format details, so the baseline of 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the resource ('jobs saved on the user's Ocean of Jobs account') and ordering ('newest saved first'), and it references the same fields as search results. It distinguishes the saved-jobs scope from general search, though it does not explicitly name a sibling alternative like search_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?

The description implies the tool is for viewing a user's saved jobs but gives no explicit when-to-use guidance, no conditions for choosing it over siblings such as search_jobs or get_job, and no when-not-to-use notes.

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: discloses that a real application is sent, that off-board jobs are refused, that duplicate queueing is harmless/idempotent in effect, that already-applied-or-in-progress jobs are refused, and that a personal access token is required. This is exactly the consequential-action context an agent 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-loads the action and mechanism, then lays out prerequisites and refusal rules in a logical order. Dense but each sentence carries a distinct rule; slightly long, though nothing is clearly wasteful.

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-param mutation tool with an output schema and annotations present, the description covers the safety profile, prerequisites, refusal conditions, and idempotency. 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?

With one parameter and 100% schema description coverage, the schema already explains the 'id' field. The description does not add format or sourcing guidance beyond what the schema provides, 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 (queue a job for auto apply via the Ocean of Jobs Chrome extension) and explains the mechanism (extension applies on next 15-minute check with the user's profile/resume). This clearly separates it from list_auto_apply_queue and remove_from_auto_apply_queue.

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 gives the when ('queue a job only when the user asks for it'), the prerequisites (extension installed and connected, the MCP auto-apply setting enabled, a personal access token), and the acceptable sites (Greenhouse/Ashby/Workable), instructing the agent to pick only those 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations by stating the auth requirement ('Needs the user's personal access token') and the narrow time window in which the removal is meaningful, though it says nothing about what the caller receives back or what happens if the extension has already applied.

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

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

Two short sentences with no filler; the core action is front-loaded and the auth caveat follows as a secondary note. Nothing could be trimmed without losing meaning.

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 no explanation, and annotations cover destructiveness and idempotency. The description supplies the two things structured fields cannot: the auth prerequisite and the timing semantics of the queue, leaving no material gap for an agent invoking it.

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?

With a single required parameter and 100% schema description coverage, the schema fully documents 'id'. The description adds no format, source, or constraint information about the identifier, so the baseline of 3 for schema-saturated params 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?

The description gives a specific verb ('take a job out of') and resource ('the user's auto apply queue'), and the timing clause 'before the extension applies to it' pins down what is being removed. It implicitly distinguishes itself from remove_saved_job by naming the auto apply queue, but never explicitly contrasts the two siblings, so it stops short of a fully differentiating 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?

Usage context is implied by 'before the extension applies to it', which tells the agent this is a pre-emptive removal of a pending item. There is no explicit when-not guidance and no routing to alternatives such as remove_saved_job or list_auto_apply_queue, so the agent must infer the boundary between queue removal and saved-job removal.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description usefully adds that a personal access token is required, and the wording 'off the saved list' clarifies the job entity itself is not deleted, which softens the destructive flag.

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

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

Two short sentences with no waste; the action is front-loaded ahead of the auth prerequisite.

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

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

With an output schema present and rich annotations, the description needn't explain return values or safety. The main residual gap is the absence of sibling routing for when to remove versus re-save or list.

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 (id) and schema coverage is 100%, so the schema already documents it. The description adds no syntax, format, or source detail for the id beyond what the schema provides, matching the 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?

Names a specific verb and resource: removing a job from the saved list. The action is unambiguous and the inverse of the sibling save_job, though it never explicitly names an alternative to route between.

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 prerequisite (personal access token) but no guidance on when to use this versus list_saved_jobs or save_job, and no exclusions or conditions for selecting it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered; the description still earns credit by adding the authentication requirement ('Needs the user's personal access token') and the cross-device persistence effect, neither of which appears in the annotations. It stops short of saying what happens on an unknown or malformed job id.

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

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

Three short sentences, outcome stated first, with no preamble. The final sentence about duplicate saves largely restates idempotentHint from the annotations, so it is mild redundancy rather than wasted space.

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

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

For a one-parameter mutation with full annotation coverage and an output schema, the description covers the essentials: target account, auth need, resulting visibility, and duplicate-save tolerance. Only minor gaps remain around failure behavior for an invalid id.

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

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

Schema coverage is 100% and the single parameter 'id' is fully documented in the schema with an example, so the baseline applies. The description adds no format or acquisition guidance (e.g. that the id comes from search_jobs or get_job) beyond what the schema already says.

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 ('Save') plus resource ('a job') plus the destination account, and it states the observable outcome (appears under Saved jobs on every device). The verb pairs cleanly against the inverse sibling remove_saved_job and the reader list_saved_jobs, so an agent can pick it 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?

The description supplies a usage-relevant fact ('Saving the same job twice is harmless') but never says when to reach for this instead of remove_saved_job or list_saved_jobs, nor that it requires an authenticated account context beyond the token mention. Usage is implied by the tool name rather than spelled out.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, but the description adds substantial behavior beyond that: up to 25 results per call, best-match ordering with a query and newest-first otherwise, total match count, and lifetime/link fields on every job. There is no contradiction with annotations.

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 front-loaded with what the tool returns, then organized into a useful "How to search well" list. It is longer than strictly necessary for a tool description, but most sentences contribute concrete operational guidance rather than 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?

Given the 10-parameter search surface and the existing output schema, the description is complete enough for correct invocation: it covers the main filter constraint, search strategy, ordering, result limit, and important returned fields. The annotations and output schema carry the rest of the safety and return-shape burden.

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 60%, so the description carries meaningful additional semantics: query words must all match, short title/skill terms work best, and at least one of query/company/city/country should be supplied. It also clarifies country codes and common listing geography, though it leaves some parameters such as offset and salary_min mostly to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ("Search open jobs on Ocean of Jobs") and immediately explains scope, result ordering, and key return fields. It also distinguishes itself from the detail sibling by instructing the agent to use get_job for full descriptions.

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 explicitly states that at least one of query, company, city, or country should be provided, and gives clear search tactics: use short core terms, search once, broaden once if needed, deduplicate by id/apply_url, and open only the strongest candidates with get_job. This is unusually complete when-to-use and how-to-use 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?

Goes beyond the annotations by stating the side-effect boundary (status and credits are untouched) and the auth requirement ('Needs the user's personal access token'). Since annotations already declare idempotentHint=true and destructiveHint=false, the description's contribution is supplementary rather than load-bearing, but it is real and useful.

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, front-loaded with the action and its value set before the guardrail and the side-effect disclaimer. No sentence is filler; even the auth note 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?

With an output schema present, return values need no explanation, and the description covers intent, guardrail, side effects and auth. The only minor gap is that the dependency on list_auto_apply_history for the id lives solely in the schema rather than the description.

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

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

Schema coverage is only 50% — the outcome enum has no schema description — so the description carries the burden and does so by listing every enum value and explaining the non-obvious 'none to clear it' as a reset. It leaves the id parameter to the schema, which already documents its source, so this is close to complete.

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 ('Record what the user says happened with an application that went out') and enumerates the full outcome vocabulary, including the special 'none to clear it' case. An agent can distinguish this from list_auto_apply_history or queue_for_auto_apply 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 gating condition — 'Only when the user tells you; never guess' — which is exactly the when/when-not guidance an agent needs for a user-reported fact. It also bounds the scope of the write ('It changes nothing else'), so the agent knows no adjacent state is affected.

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 substantive context beyond the annotations: the auth requirement ('Needs the user's personal access token') and, critically, the temporal semantics of a filter change ('A new filter starts from now: jobs already open are not emailed'). That non-obvious side effect is exactly the kind of behavior an agent cannot get from readOnlyHint/destructiveHint/idempotentHint.

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 operation set, followed by the caveat and the prerequisite. No filler and no repetition of schema content.

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 full schema coverage, annotations, and an output schema, the description supplies everything else an agent needs: the operation set, the side effect of replacing a filter, and the token requirement. Nothing material 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 each nested filter field carries its own description, so the schema already does the heavy lifting. The description reinforces replace-not-merge semantics for `filter`, but the schema's own 'It replaces the old one' already states that, so the added value is marginal.

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 the specific resource (a job alert) and enumerates the exact operations available: pause, resume, or replace the filter. This is immediately distinguishable from the sibling write tools create_alert and delete_alert, which cover creation and removal rather than modification.

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

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

The three supported mutations define the scope of use clearly, so an agent knows this is the tool for toggling or retargeting an existing alert. It stops short of explicit routing language (e.g. 'to remove an alert use delete_alert', 'to see alerts use list_alerts'), so the exclusion side is left to inference from sibling names.

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 non-read-only, idempotent, non-destructive, closed-world, but the description adds substantial context beyond them: partial-update semantics, the fact that list fields are replaced wholesale, that unrecognized skills are silently dropped, and that the response echoes what was kept. The auth requirement (personal access token) is also called out. It stops short of describing error behavior if the token is missing.

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 the mutation model before the validation caveat and the usage constraint. Dense but every clause carries information; the final permission sentence is slightly orphaned from the rest.

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 need not be explained, and the description still notes the response reports retained values. With 10 optional parameters, the description supplies the two things that matter most: partial-update behavior and the read-before-write workflow.

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 80%, so field meanings and formats are largely handled by the schema. The description nonetheless adds the crucial semantic the schema omits: providing a list field replaces rather than appends, which changes how an agent should construct the call. It does not clarify interactions between digest_day, digest_time, and cadence.

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: change the user's search preferences. It also implicitly separates itself from the read sibling by telling the agent to read get_preferences first, though it does not explicitly name update_alert as the alternative for alert configuration.

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 prerequisite (read get_preferences first), a scoping rule for when it should fire (only when the user asks), and the condition that selects a different tool for inspection versus mutation. 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.