freehire

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

The annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is covered structurally. The description adds that a single saved screening answer is deleted and that the id comes from answer_bank_list, but it does not add details such as permanence, permissions, or failure 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 front-loaded sentence with no redundant or filler wording. The verb and resource appear immediately, followed by the practical detail about obtaining the id.

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 with annotations covering the safety profile and no output schema, the description is largely complete: it says what is deleted and where the id comes from. It could be stronger by explicitly noting that deletion is permanent or that the id must be valid, but the annotations already communicate destructiveness.

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 compensate for the undocumented id parameter. It does add useful meaning by saying the id is the one shown by answer_bank_list, but it does not explain constraints such as whether the id must belong to the person or what happens if it is invalid.

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 uses a specific verb, "Delete," and identifies the resource as one of the person's saved screening answers. It also points to answer_bank_list as the source of the id, which helps distinguish it from the listing sibling, though it does not explicitly name save/set alternatives.

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 phrase "by the id answer_bank_list shows" gives implied usage guidance by telling the agent where to obtain the required id. However, it does not state when to use this tool versus answer_bank_save or screening_answers_set, nor does it include exclusions or cautions.

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, destructiveHint=false, openWorldHint=true, and idempotentHint=false, so the agent knows this is a non-mutating read. The description adds useful context about how the answers are consumed by auto-apply, but says nothing about ordering, volume, or whether answers are per-user or per-employer scoped.

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 first identifies what is returned and gives illustrative examples, the second supplies the reason it matters. Front-loaded and appropriately sized for a parameterless list tool.

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 zero-parameter, read-only list tool whose safety profile is fully covered by annotations, the description supplies enough to call it correctly. The only minor gap is the absence of any hint at the return shape, which matters slightly since there is no 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?

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter semantics for the description to explain. Schema description coverage is 100% and the schema is an empty object, so nothing is left undocumented.

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 plus resource: lists the person's saved answers to open-ended screening questions, with two concrete example questions that make the content unambiguous. It does not differentiate itself from the sibling screening_answers_get, so an agent could hesitate between the two, but the core purpose is 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 second sentence implies why the list matters ('automatic applications reuse them on every form that asks the same question'), which hints at review-before-auto-apply usage. However, it never states when to call this versus screening_answers_get, answer_bank_save, or answer_bank_delete, and gives no prerequisites or exclusions.

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 flag destructiveHint=true and openWorldHint=true; the description adds meaningful context beyond that — the answer is transmitted to employers in the person's name and must be the person's own words, not composed or guessed. It also names exactly what gets destroyed ('replaces an earlier answer to the same question').

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 action and followed by the critical integrity constraint and the replace behavior. No filler, and the most important warning is emphasized rather than buried.

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 write tool with no output schema, it covers source of input, integrity constraint, and overwrite semantics, which is most of what an agent needs. It could still be clearer about the distinction from screening_answers_set and whether a confirmation is returned.

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 says 'The person's answer, in their words' and 'The question as the form words it,' so the description largely restates those semantics. The only additive element is the pointer to auto_apply_get as the authoritative source for the question string.

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 ('Save the person's answer to one screening question') and adds the downstream purpose ('so automatic applications can send it'). It points to auto_apply_get as the source of the question wording, but does not distinguish itself from the similarly named sibling screening_answers_set.

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 partial routing guidance by saying to take the question wording from auto_apply_get, and clarifies the replace-on-repeat behavior. However, it never states when to use this versus screening_answers_set or answer_bank_list/delete, which an agent must disambiguate on its own.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description usefully adds that no submission to the employer occurs, which is real behavioral context, but it says nothing about repeat calls (despite idempotentHint=false) or what happens if the vacancy was never applied to.

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, zero filler, with the core action stated first and the most dangerous misreading (that this submits an application) corrected immediately after.

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 tool with full schema coverage and annotations that declare the mutation profile, the description covers what an agent needs to select and call it. The only mild gap is behavior on repeated or invalid calls, which matters given idempotentHint=false.

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% with a single required 'slug' parameter whose schema description points to the vacancy's public_slug. The description adds no meaning beyond that, 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?

The description gives a specific verb and resource ('Mark a vacancy as applied to') and immediately clarifies the crucial scope boundary: this records the user's own application rather than submitting anything. That separates it from the auto_apply_* siblings in spirit, though it never names save_job/track_job/auto_apply_start 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?

Usage is implied rather than stated: the second sentence tells the agent this is for applications the user already made themselves, which is meaningful routing guidance away from auto_apply_* tools. There is no explicit 'use this when / use X instead when' statement or mention of prerequisites.

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=false, so the safety profile is largely covered. The description still contributes real behavioral context the annotations cannot express: the transient refusal during submission and, importantly, that history is preserved after withdrawal, which tempers 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?

Three short sentences, each carrying distinct information: what it does, when it fails, and what persists. Front-loaded with the action and no redundant restatement 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?

For a one-parameter destructive mutation with no output schema, the description covers the essential facts an agent needs: the eligible state, the failure condition, and the durability of history. It could go slightly further by indicating what the caller should do after a refusal, but nothing critical 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 the single parameter already documents the expected slug format and references search_jobs and my_jobs as the source. The description adds no further meaning about job_slug, so this sits at the baseline where the schema does the work.

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 ('Withdraw an automatic application') and scopes it with a precondition ('that has not been submitted'), which separates it from siblings like auto_apply_start, auto_apply_retry and auto_apply_review. It stops short of naming any sibling explicitly, so differentiation is inferred from the precondition rather than stated.

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 when-to-use boundary is explicit: only applications that have not been submitted can be withdrawn, and the call is refused during submission. What is missing is routing guidance for the excluded case – if the application has already been submitted, the description does not point the agent to any alternative action.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds the non-obvious behavioral fact that history is append-only and grows with each call, which neatly explains the idempotentHint=false annotation and tells the agent polling is safe and progressive. It stops short of describing error behavior for an unknown or invalid slug.

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, front-loaded with the core action and the returned payload, with the polling tip as a trailing clause. There is no filler or repetition of the title beyond what is needed.

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?

There is no output schema, so the description correctly compensates by enumerating the fields returned, including the actionable 'what to do next'. What remains uncovered is failure handling for a missing or invalid job_slug and the shape of the history entries, a minor gap for a single-parameter read.

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 single job_slug parameter already documents that it comes from search_jobs and my_jobs. The description adds no further meaning about the parameter, so the schema does all the work and the baseline 3 applies.

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

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

The description names a specific verb and resource ('Read where one automatic application stands') and enumerates what is returned: status, stopped-on questions, missing answers, history, and next steps. The singular scope ('one automatic application') implicitly separates it from the list-style sibling auto_apply_list, but no sibling is named explicitly, so an agent must infer the boundary.

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

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

'Call it again to follow progress' gives real guidance on repeated invocation, which is more than most status tools offer. However, it never says when to prefer this over auto_apply_list, auto_apply_review, or auto_apply_retry, nor any precondition such as having started an application first, so the when-to-use guidance remains 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 cover safety (readOnlyHint true, destructiveHint false, openWorldHint true), so the description only needs to add scope. It does: the result set is bounded to live attempts plus those from the last 30 days, and each entry carries status and a last-event timestamp — behavior an agent could not infer from 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?

Two sentences, zero filler. The result scope is front-loaded and the sibling routing comes second, which is the right order for an agent deciding whether to call this tool.

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 no parameters and no output schema, the description carries the burden of describing the return, and it does so at a high level (status plus last-activity time). It omits ordering, result caps/pagination, and what status values are possible, which leaves minor gaps for a 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 for the description to disambiguate; the baseline for a zero-param tool applies. The description does at least make clear that no filtering argument is needed and that the 30-day window is fixed behavior rather than a caller-supplied option.

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 ("List the person's automatic applications") and immediately defines scope: live attempts with status and last-activity time, plus those submitted in the last 30 days. That is enough for an agent to distinguish it from auto_apply_get, auto_apply_cancel, or auto_apply_retry 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?

It explicitly routes the agent to auto_apply_get when it needs one attempt's questions and history, which is the closest competing tool. It stops short of addressing the other auto_apply_* siblings (cancel, retry, review, start), so the guidance is clear but not exhaustive.

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=false, and openWorldHint=true, but the description adds real operational context beyond them: the refusal cases and the prerequisite step are not derivable from the structured fields. It stops short of saying what a successful restart actually triggers (immediate re-submission, async retry, credit cost) or what is returned, 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?

Two sentences, front-loaded with the qualifying states, then the prerequisite, then the refusal conditions. Despite the em-dash list, every clause carries decision-relevant information with 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?

For a single-parameter mutation tool with no output schema, the description covers the trigger conditions, prerequisites, and refusal cases well. The remaining gap is what to expect after a successful retry (state change, timing, or how to confirm progress via auto_apply_get/auto_apply_list), which 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?

Only one parameter, job_slug, and the schema already documents it at 100% coverage including where to obtain it (search_jobs, my_jobs). The description adds no further meaning about the identifier, so the baseline 3 applies.

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

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

States a specific verb (restart/refresh) on a specific resource (an automatic application) and enumerates the exact states that qualify: stopped on an unanswered question, after repeated errors, CV not tailorable, or awaiting review. This clearly separates it from auto_apply_start, auto_apply_review, and auto_apply_cancel.

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 preconditions (answer open questions via answer_bank_save or screening_answers_set first) and explicit exclusions (refused for a declined attempt or one that may already have reached the employer). An agent knows both when to call it and when the call will fail.

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, non-idempotent and open-world, so the bar is lower, yet the description adds real consequences: 'approved' submits to the employer using the tailored CV and the answers auto_apply_get reveals, while 'declined' stops it permanently. The remaining gap is that it doesn't say what happens if the status is not pending_review or what a successful response contains.

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 sentences, front-loaded with the precondition before the two outcomes. The dense second sentence with semicolon-joined clauses is slightly harder to parse but every clause carries information about behavior.

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 no output schema, the description covers the precondition, both outcomes, and the irreversibility of a decision. What is missing is the error case (wrong status) and any confirmation of what the call returns, which are minor for this complexity level.

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 50%: job_slug is documented in the schema, but the decision enum carries no schema description. The description compensates by explaining precisely what each enum value does, which is the more important semantic gap to close.

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 ('Record the review'), the exact resource (an automatic application whose status is pending_review), and the two possible outcomes with their consequences. An agent can distinguish this from auto_apply_get, auto_apply_retry and auto_apply_cancel from the text 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?

It gives a clear precondition (the application must be in pending_review) and a constraint ('One decision per attempt'), which implies no retry. It does not explicitly name auto_apply_retry as the path once a decision is recorded, so the routing guidance stops just short of a full when/when-not statement.

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

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

Annotations already declare this is a non-read-only, non-idempotent, open-world write, so the safety profile is covered. The description adds value beyond them by disclosing the consumption of a daily quota, the ATS-support restriction, and the crucial fact that submission is deferred until an auto_apply_review step. It does not say what happens if the allowance is exhausted or how partial state is handled on failure (relevant given idempotentHint=false).

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

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

Front-loaded with the action, then three short sentences each carrying distinct, useful information (quota cost, eligibility restriction, progress tracking). No filler, though the phrasing around the review step is slightly 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?

For a one-parameter mutation with no output schema, the description covers the whole lifecycle: what is started, what the system does on the user's behalf, that it pauses for review, what it costs, and which sibling reports progress. Nothing an agent needs in order 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?

There is a single parameter and the input schema already documents it fully at 100% coverage, including where the slug comes from (search_jobs, my_jobs). The description adds no further information about the slug format or validation, so the schema does the work and 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?

The description opens with a specific verb and resource ('Start applying to a vacancy automatically') and immediately distinguishes the operation from a plain apply by describing the automated pipeline (CV tailoring, form checking, review gate). The phrase 'on the person's behalf' and the named review step leave no ambiguity about what this call initiates.

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 real preconditions: the vacancy must be on a supported applicant-tracking system, and starting costs one of today's auto-apply allowance. It also routes the agent to siblings ('waits for a review (auto_apply_review)' and 'Follow progress with auto_apply_get'). It stops short of explicitly contrasting with apply_job for manual applications, so it is not a full when/when-not/alternative statement.

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, open-world and non-destructive behavior, so the description's added context is the useful part: the 50-per-call batch ceiling and the tri-state result model (open, closed, not_found) with closure/last-seen timestamps. It does not explain why the tool is non-idempotent (statuses are point-in-time and change), which would have closed the remaining gap.

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

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

One sentence, front-loaded with the core action, then the input source, batch limit, and return shape. No filler or redundant phrasing.

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, rich annotations, and a fully documented single parameter, the description covers everything needed to invoke it correctly. Only minor gaps remain, such as the point-in-time nature of the results or how not_found should be interpreted.

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 there is a single parameter, so the schema already documents 'slugs' and the 50-item limit. The description only restates that the identifiers come from search results' slug field, adding little beyond the structured definition.

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 ('check whether postings are still open') scoped to slugs carried by search results, which cleanly separates it from fetch/get_job style lookups in the sibling list. An agent can tell this is a status probe, not a detail retrieval.

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: 'Use before acting on a saved shortlist.' It does not name a when-not condition or point to a specific alternative (e.g. get_job for full details), so it stops short of a 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 cover read-only, non-destructive, open-world, and non-idempotent, so the safety profile is settled; the description adds that the vocabulary is 'live' (explaining the non-idempotent hint) and that each value carries a vacancy count plus numeric ranges. That return-shape information is genuinely useful because there is no output schema. It does not mention size, cost, or the circular note that the `filters` argument expects values produced by this same tool.

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

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

Two sentences, front-loaded with what the tool returns, then the imperative usage rule and the skill-slug caveat. No filler, no restated title, nothing that could be cut without losing 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 zero-required-parameter discovery tool this is largely callable as-is, and the description covers purpose, timing, and rough return shape. What is missing is differentiation from 'list_filter_values' and any explanation of how to use the 34-key `filters` slice, which is the only real complexity in the definition.

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 there is a single optional nested `filters` object, so the baseline is 3. The description says nothing about narrowing the vocabulary or what happens to counts when a slice is applied; the schema's own note ('Each value is a list of values from the facets tool') is self-referential and the description does not clarify it.

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 uses a specific verb and resource ('List the live filter vocabulary: every filter's valid values with a vacancy count each, plus numeric ranges'), which is far more than a restatement of the title. An agent knows exactly what comes back: per-value counts and numeric ranges. It stops short of a 5 because the near-identical sibling 'list_filter_values' is never mentioned, leaving ambiguity about which of the two to call.

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 sequencing guidance is given ('Call this BEFORE filtering a search'), plus a hard constraint ('never invent a filter value'), which is exactly the failure mode this tool prevents. No exclusions or when-not-to-use guidance is provided, and it does not route the agent away from the sibling 'list_filter_values'.

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, destructiveHint=false and openWorldHint=true, so the safety and access profile is covered. The description adds only a liveness signal ('whether it still looks live'), which is the one useful non-annotation hint; it says nothing about auth, rate limits, or freshness guarantees, and most of the sentence restates return contents.

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 sentence that front-loads the action and scope with no filler. The trailing return-value list is slightly awkward phraseology but does not bloat the text.

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

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

For a single-parameter read tool with an output schema and full annotation coverage, the description covers purpose and input provenance adequately. Its gap is the missing differentiation from the sibling 'get_job', which is the one thing an agent still needs.

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 documents 'id' as 'a result id from search'. The description's 'by an id search returned' reinforces the provenance but adds no format, validation, or nominal-vs-internal distinction beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read one posting in full') plus the identifier source, so the job is unambiguous. It does not, however, differentiate itself from the sibling 'get_job', which by name appears to do something very similar.

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 'by an id search returned', which tells the agent the id must come from a prior search step. There is no explicit when-to-use/when-not guidance and no routing against 'get_job' or 'search_jobs', leaving the agent to guess which retrieval tool to pick.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that the payload is the stored profile fields ('what they do, which industries..., how many postings'), which is largely restated by the output schema; no permissions, staleness, or caching behavior is disclosed.

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 well-formed sentence with the action and the lookup key front-loaded, and no filler. The trailing enumeration of returned fields is mildly redundant given the output schema, which keeps it from a 5.

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

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

With one required parameter, full schema coverage, an output schema, and annotations covering the safety profile, the description supplies everything needed to invoke correctly. The only shortfall is the absence of sibling routing for an agent choosing between search_companies and this 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?

There is a single parameter with 100% schema description coverage, so the schema already explains that slug is the employer identifier matching a result's company_slug. The description reinforces provenance ('as the slug a result carries') but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Read what freehire holds about one employer') and enumerates the resource's attributes, so the agent knows this is a single-employer lookup rather than a list. It does not name any sibling explicitly (search_companies, get_job), so differentiation is inferential rather than stated.

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?

'by the slug a result carries' implies this tool is used to expand a company that appeared in a prior search result, which is genuine usage context. However, there is no explicit when-to-use/when-not statement and no named alternative, so the guidance remains 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 readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=false, so the safety profile is covered. The description's extra content is about returned fields (liveness, reality class, ATS) rather than behavior, and an output schema exists to document those, so it adds only modest value beyond the structured data.

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

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

Front-loaded with the verb and the key, single sentence with no filler. It is somewhat long because it enumerates return fields that the output schema already covers, which is mild redundancy rather than bloat.

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 read tool with a full schema, full annotation coverage and an output schema, the essentials are present: what it returns and where the slug comes from. The only real gap is routing guidance against siblings like check_jobs_open or fetch.

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 single parameter is fully documented in the schema itself ('the posting's identifier, as carried by a search result's slug'). The description's 'by the slug a search result carries' merely restates that, adding no format or provenance detail beyond it.

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 ('Read') plus a precisely scoped resource ('one posting in full') and an explicit retrieval key ('the slug a search result carries'), which cleanly separates it from the plural search/list siblings (search_jobs, check_jobs_open). The enumeration of what comes back makes the tool's identity unambiguous.

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 tells the agent the prerequisite for calling it — the slug must come from a search result — which implies the search_jobs → get_job workflow. It does not name an alternative or state when not to use it (e.g. versus check_jobs_open for bulk liveness checks), so it stops short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's job is to add content-level semantics, which it does: contacts are explicitly excluded, and the experience section is flagged as reporting "the SHAPE" of evidence rather than achievements — a real interpretation caveat. It stops short of describing the empty/no-profile state, so an agent doesn't know what a missing profile returns.

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 purpose is front-loaded and every sentence carries information: contents, call-ordering rule, and a semantic caveat about the experience section. The trailing "Takes no arguments" is mildly redundant with the empty schema but still cheap and useful; the parenthetical field list is dense but well-formed.

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?

There is no output schema, so the description carries the return-shape burden and does so by naming the sections returned (roles, avoided skills, work preferences, CV headline/years/experience/education) and the exclusion of contacts. Combined with the call-ordering instruction, an agent has everything needed to invoke and interpret this 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?

With zero parameters the baseline is 4, and "Takes no arguments" explicitly confirms the empty schema rather than leaving the agent to infer it. No additional meaning is needed or possible here.

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 ("Read the user's saved job-search profile") and immediately enumerates what that profile contains: target roles/skills, avoided skills, work location/mode, and CV sections. No sibling tool reads the user's own profile, so an agent can distinguish this from search/facets/stats tools 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?

It gives an explicit when-to-use rule: "Call this before asking the user what they are looking for; only ask about what the profile does not answer." That is both a trigger and a boundary condition (don't re-ask what the profile answers), which is exactly the guidance an agent needs to sequence this call ahead of clarifying questions.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the result is a count plus facet breakdowns, which is genuinely beyond the annotations. It says nothing about pagination behavior despite limit/offset parameters, or about how the facets are ranked or truncated.

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 sentences, no filler, and the output shape (count plus breakdowns) is front-loaded before the filter note. Nothing could be removed without losing 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 23-parameter, zero-required aggregate tool with an output schema, the definition covers what is returned and how filters relate to search. It omits what happens with no filters (whole-market aggregate), how many facet values come back, and whether limit/offset affect the facets, which an agent needs to interpret results correctly.

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

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

Schema coverage is 78% and the schema itself documents most filters in depth, including query operators and enum values. The only parameter-level contribution from the description is that the filter set is shared with job search, which tells the agent to reuse known filter semantics. That is useful but modest, so the baseline of 3 is right.

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: counting open postings that match filters and returning the most common role families, seniorities, skills, work modes, countries and regions. That clearly separates it from search_jobs (which returns postings) and salary_stats (which returns pay). It stops short of naming any sibling explicitly, so the differentiation is inferential rather than stated.

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 line "Takes the same filters as a job search" implies you use this after or instead of a listing search when you want aggregate distribution rather than individual postings. There is no explicit when-to-use, when-not-to-use, or an alternative tool named (salary_stats and search_jobs are the obvious ones), so the agent has to infer the routing.

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/openWorld/non-destructive, so the safety profile is covered; the description adds genuine value with result ordering (most common first) and the closed-world contract that unlisted values match nothing. It does not discuss truncation behavior when limit is hit, which is the main remaining ambiguity for a capped listing tool.

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

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

Two sentences, front-loaded with what is returned and how it is ordered, followed by the usage rule. No filler or restatement of the name.

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 needn't be explained, annotations carry the safety profile, and the description still covers ordering, the closed-world value contract, and when to call it. For a three-parameter read tool, nothing an agent needs is missing.

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

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

Schema coverage is 100%, with all three parameters documented including the allowed filter names and the skills alias behavior for 'contains', so the baseline is 3. The description's enumeration ('skills, categories, seniorities, sources, countries and the rest') only restates a subset of the schema's filter list and adds no new 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?

States a specific resource (the enumerable values of one job-search filter) with concrete examples of filter families, and adds two distinguishing properties: counts of open postings and 'most common first' ordering. An agent can tell this apart from search_jobs, job_market_stats and salary_stats without opening schemas.

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

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

'Use it before filtering on a value you are not sure of' gives an explicit when-to-use condition, and 'a value not listed matches no posting' explains the consequence of skipping it. It stops short of naming the sibling search tool whose filters it feeds, so it is clear context rather than full alternative routing.

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, destructiveHint false, and openWorldHint, so the closing "Effect: none, read-only" earns no credit. The added value is elsewhere: the description discloses the per-channel delivery state (active flag, pending matches, last delivery) and the round-trip caveat that `other` carries website-only filters preserved by updates — behavior an agent could not infer from the 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?

A single dense sentence, front-loaded with the verb and resource, followed by a short clarification and an effect statement. The field enumeration is long but each item earns its place because there is no output schema; minor cost is that the channel details are crammed into the same sentence as the top-level fields.

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 no output schema, the description carries the burden of describing returns, and it does cover alert fields, channel state, and the account-wide delivery_schedule. It omits ordering, cardinality limits, and what an empty result looks like, which matters for an agent deciding whether a missing alert means nothing is configured.

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 for a parameterless tool is 4. The mention of query, filters, salary_min/max and `other` describes return payload fields rather than inputs, which is still useful but does not add parameter meaning.

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?

Opens with a specific verb and resource ("List the person's job alerts") and enumerates exactly what each alert record contains, which separates it from mutation siblings like update_subscription and unsubscribe. It does not explicitly name an alternative tool, so it stops short of a 5, but an agent can tell what this returns 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?

Usage is only implied: it says the search is returned "as the structured object the alert tools take" and that `other` holds "website-only filters an update keeps," which hints this is the read side of an update round-trip. There is no explicit statement of when to call this versus subscription_updates or update_subscription, and no exclusions.

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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds genuine behavioral context: the query runs against 'live' market data and returns a three-part analytical result (share of vacancies, skills held, missing skills ranked by vacancy unlock), which is the only place the return shape is disclosed since no output schema exists.

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

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

Front-loads the verb and resource, then packs the three result metrics into one structured clause; the closing disambiguation sentence is short and load-bearing. Slightly dense but nothing is redundant.

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

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

For a tool with a large nested filter object and no output schema, the description supplies the essential missing pieces: the nature of the live data source, the result metrics, and the measured-vs-filter distinction. It omits only secondary details such as filter combination semantics and behavior on empty input.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns a bump by resolving a real ambiguity: `skills` is the MEASURED set, not a filter, distinguishing it from `filters.skills`. It still does not explain how the ~30 facet filters combine (AND vs OR) or what happens with an empty skill list.

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 (score a skill list) against a specific resource (live open-vacancy market) scoped by a filtered role, and enumerates the three outputs: coverage share, must-have skills held, and missing skills that unlock vacancies. This is clearly distinguishable from siblings like facets or job_market_stats.

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 rather than stated: the agent must infer that filters come from the facets tool (only noted in the schema) and that this is a measurement query, not a search. There is no explicit when-to-use/when-not guidance or named alternative sibling.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered without prose. The description's only added behavioral detail is that each row carries its stage and note, which is useful but thin; it says nothing about ordering, truncation when limit is hit, or why openWorldHint is set on an apparently user-scoped listing.

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 em-dash-delimited sentence with zero waste: the resource comes first, the available slices next, and the returned fields last. Nothing redundant with the title.

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-optional-parameter read tool with full schema documentation and no output schema, the description is largely sufficient — it even sketches the returned shape (stage and note). Only the omission of 'dismissed'/'all' from its slice list and the absence of any result-ordering hint keep it from a 5.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the baseline is 3. The description adds a partial enumeration of filter values ('saved, applied, viewed or the whole board') but omits 'all' and 'dismissed' from the schema enum, so it neither extends nor fully mirrors the schema's meaning.

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 pairs a specific verb ('List') with a specific resource ('the vacancies the user is tracking') and even enumerates the slices covered, so an agent can distinguish it from search_jobs or track_job. It stops short of naming a sibling alternative explicitly, which keeps it out of 5 territory.

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 user is tracking' — this is the retrieval counterpart to track_job/save_job/apply_job — but the description never states when to prefer it over search_jobs or get_job, nor any exclusions. Adequate for a simple read tool but leaves routing to inference.

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

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

Beyond the annotations, it discloses where the report goes (freehire moderators, human review) and, importantly, what it does NOT do (does not hide the job, does not change the user's own board), which is the non-obvious side-effect an agent needs. It also surfaces a real constraint — one open report per job per user — that explains the idempotentHint=false annotation without 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?

Four sentences, each earning its place: purpose first, then routing to moderators, then the effect it does not have, then the consent gate and duplicate rule. Front-loaded and free of repetition of the name or title.

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 non-destructive mutation with no output schema, the description covers audience, review process, side effects, consent, and the one-open-report limit — enough to call it correctly. It does not say what the call returns (report id, status) or whether a report can be withdrawn, which are the remaining gaps.

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 reason enum already carries per-value explanations, so the schema does the heavy lifting. The description's list of reportable conditions loosely mirrors the enum but adds no syntax, format, or constraint detail beyond it; 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?

The description gives a specific verb+resource ("File a report on a vacancy") and enumerates the qualifying conditions (fake, spam, scam, irrelevant, never answers). It is not, however, differentiated from the sibling report_problem, so an agent must infer which reporting tool handles a broken platform feature versus a bad vacancy.

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 a clear gate: only report when the user asks, or after disclosing what will be sent and getting agreement — a genuinely useful when-to-use rule. It stops short of naming the alternative tool (report_problem) for non-job issues, so the routing decision against siblings is left partly implicit.

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 the safety profile (not read-only, open-world, not idempotent, not destructive), and the description adds substantial context beyond them: a successful receipt means the report was recorded, not fixed, and no reply is guaranteed. It also discloses that repeated matching open reports increment request_count, which is a concrete rate/dedupe behavior an agent cannot infer from the 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?

Five sentences, all functional, with the purpose front-loaded before constraints and receipt semantics. There is mild duplication between the privacy admonition and the schema's 'Summarize errors without sensitive payloads' note, 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?

For a six-parameter, four-required submission tool with no output schema, the description covers purpose, trigger conditions, content guidance, privacy limits, and what the response does and does not mean — everything an agent needs to submit a well-formed report and interpret success.

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 high (83%), so the baseline is 3, but the description earns more by telling the agent what to write in each field — concise goal/expected/actual summaries, include tool_name and error_code when known — and by constraining content with an explicit sensitive-data exclusion list (conversations, CV contents, credentials, tokens, contact details, URL query strings).

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 uses a specific verb (report) plus an enumerated set of resources — an incomplete operation, a missing capability, or unexpected behavior — matching the category enum. It is clearly distinguishable from sibling tools like report_job, though it never names that sibling to make the boundary 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?

'Use only for an observed problem, and never report a failure of report_problem itself recursively' gives an explicit when-to-use and a clear when-not. What is missing is any comparison to the closest sibling (report_job), leaving the agent to infer that job-listing problems go elsewhere.

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/openWorld/destructive=false, so the description is free to add higher-value semantics: it discloses that a sample size accompanies each figure and that currencies and pay periods are reported separately and never converted. That last caveat is essential for correct interpretation and is not derivable from annotations or schema. It stops short of documenting coverage thresholds or how small samples are handled.

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 sentences, no filler, and the most important information (what the numbers are and that they come only from postings stating pay) is front-loaded ahead of the interpretation caveat.

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 covers source, scope, and the currency/sample-size caveats an agent needs to read results correctly. The one gap is that all three parameters are optional with no stated default or behavior for an unfiltered call, which matters given zero required parameters.

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

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

Schema description coverage is 100% and every parameter (country, category, seniority) is already documented with format and example values in the schema. The description restates the same scoping axes in prose without adding format, default, or combination rules, so the baseline 3 applies.

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

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

States a specific verb (report percentiles) plus the exact statistics returned (25th, median, 75th), the data source (open postings that state pay), and the scoping dimensions (role family, seniority, country). An agent can distinguish this aggregate-pay tool from job_market_stats or search_jobs 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?

Usage is implied rather than stated: the phrase 'from open postings that state pay' quietly warns that the sample is incomplete and excludes postings without salary data. No alternative sibling is named and no condition selects this tool over job_market_stats, so the routing decision is left to inference.

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

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

The only behavioral claim, 'Idempotent', merely restates idempotentHint=true from the annotations and earns no credit. With readOnlyHint=false declared, mutation behavior is in scope, yet the description says nothing about what gets created, what happens when the job is already saved, or permission requirements. The annotations cover the safety profile, so this is not a contradiction, but the description adds essentially nothing.

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 clipped sentences with zero filler and the primary action front-loaded. It is efficient, though the brevity edges toward under-specification rather than crisp completeness.

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, non-destructive bookmark tool with rich annotations and no output schema, the description is borderline sufficient. It omits the relationship to unsave_job and track_job and gives no indication of what the response confirms, leaving small but real gaps.

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 sole slug parameter is documented as the vacancy's public_slug, so the schema already carries the semantics. The description adds no extra detail about slug format, where to obtain it, or error behavior for unknown slugs.

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 ('Bookmark') and resource ('a vacancy'), so the agent knows this creates a saved-job association. It doesn't explicitly name the inverse sibling unsave_job, but the purpose is unambiguous without reading 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?

No when-to-use guidance is given: it does not mention how this differs from track_job, apply_job, or unsave_job, nor any preconditions such as whether the job must exist or the user must be authenticated. The agent must infer usage entirely from the name.

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 and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context — the exact field set returned and the rule that "a missing field has not been stated" (absent vs. negative answer) — which is useful. It says nothing about scope (which person/profile is resolved), error behavior, or the openWorldHint / non-idempotent hints, so it is good but not rich.

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 purpose is front-loaded, but the single sentence is very long and its dash-and-parenthetical construction for privacy_consent is hard to parse — it reads like a field list jammed into prose. A two-sentence split (what is returned, then the missing-field rule) would carry the same content more cleanly.

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 no output schema, the description must explain return values and it largely does by enumerating the returned fields and covering the absent-value convention. Minor gaps remain: value formats (e.g. salary units/currency, notice-period encoding) and what happens if the person has no stored answers at all are not addressed.

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 and the baseline of 4 applies. The description correctly implies the subject is resolved implicitly rather than passed in, which matches the empty schema.

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

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

States a specific verb ("Read") and resource ("the person's answers to the six screening questions") and then enumerates exactly which fields are returned — countries, visa sponsorship, salary, notice period, relocation, age, privacy_consent. This distinguishes it unambiguously from screening_answers_set without the agent needing to inspect either schema.

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

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

Usage is only implied: it is clearly the read counterpart of screening_answers_set, and the agent can infer it should be called before applying or to check whether answers exist. There is no explicit statement of when to call this versus answer_bank_list, or any prerequisite such as needing a selected profile.

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

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

Annotations declare destructiveHint=true and non-idempotent, and the description adds genuinely non-obvious behavior beyond them: omitted fields retain prior values rather than being cleared, and 'clear' must not overlap with fields being set. It also separates privacy_consent as a permission rather than a fact, which prevents a likely mis-write; nothing contradicts the 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?

Front-loaded with purpose, then timing, then write semantics, then the consent special case — a logical progression. The first sentence is long and enumerative but every clause carries information; a small amount of repetition around 'never guess or infer' could be trimmed.

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

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

For a 10-parameter, all-optional mutation tool with no output schema, the description covers exactly what an agent could get wrong: partial-update behavior, withdrawal semantics, and the consent exception. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic framing: the fields represent facts the candidate stated aloud, 'clear' means revert to unstated, and privacy_consent is scoped to employer privacy terms only. It does not restate enum or format details, which is correct since the schema carries them.

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 (record) and resource (the candidate's screening answers), then enumerates the six distinct facts covered, making the scope concrete. It is clearly a write counterpart to screening_answers_get in the sibling list, so an agent can route between them without opening either schema.

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

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

Timing is explicit: 'Call this the moment the candidate states one of these facts,' with the downstream reason given (so it can fill the next form). It also states a negative rule — never guess or infer — and covers the withdraw path via 'clear' including the two triggering situations.

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, openWorldHint, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds only the return tuple, which the output schema already provides, and says nothing about result limits, ranking, or pagination 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?

Two tight sentences with the verb and resource front-loaded and no filler. The second sentence is largely redundant with the existing output schema, which is the only 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?

Low-complexity tool: one required string parameter, an output schema covering returns, and annotations covering safety. The description is nearly sufficient, but the unresolved overlap with the sibling 'search_jobs' is a real completeness gap for tool selection.

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 with 100% schema description coverage, so the schema already documents 'query' fully. The phrase 'by free text' restates that coverage without adding syntax, format, or query-construction guidance.

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 freehire's IT job postings by free text') and discloses the return shape. However, it never distinguishes itself from the sibling 'search_jobs', which the generic name 'search' makes an obvious source of confusion for an agent picking a tool.

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?

There is no when-to-use guidance, no exclusions, and no mention of the alternatives ('search_jobs', 'fetch', 'get_job') despite a crowded sibling set. The agent gets no help deciding when this tool is the right choice.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description usefully adds that each result carries a count of open postings, which is real behavioral context. It says nothing about pagination, result ordering, or whether matching is exact or substring, leaving gaps that annotations do not fill.

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 tight sentences with no filler; the capability statement comes first and the usage rule second. Every clause carries information the 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?

An output schema exists, so return shape need not be described, and annotations cover the safety profile for this read-only open-world search. What remains missing is brief pagination guidance for limit/offset, which is the only notable hole for a 4-parameter search tool with no required fields.

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 50%: only 'query' and 'countries' are documented in the schema, and the description reinforces those ('by name', 'where they hire'). The 'limit' and 'offset' parameters are undocumented in both the schema and the description, so pagination semantics remain unexplained and the description does not compensate for that half of the gap.

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 concrete verb and resource ('find employers in freehire's catalogue') and states the two search axes (name, hiring location) plus the returned metric (open postings per employer). It distinguishes the tool from role-oriented siblings implicitly via 'question is about a company rather than about a role', but never contrasts it with get_company, which is the closest sibling for single-employer lookups.

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 an explicit selection rule: use it when the question concerns a company, not a role, which steers the agent away from search_jobs/search. It stops short of saying when NOT to use it (e.g. use get_company when you already have a specific employer identifier).

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), and the description adds real value beyond them: it discloses the return shape ('a short preview of each posting') and prescribes how to present results (table of title, company, location, posted date, link, naming the source). It does not mention pagination behavior or how `limit`/`offset` interact, which is the main remaining gap.

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

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

Purpose is front-loaded in the first sentence, and every subsequent sentence carries actionable content (query syntax, filter placement, fallback strategy, output format). It is a single dense paragraph, so the query-syntax, fallback and presentation instructions run together and would scan better as separated clauses.

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 23-parameter search tool with an output schema, the description covers the decisions that matter most: what goes in `query` versus filters, when to use `semantic`, and how to present results. It leaves pagination and several filter parameters (salary, visa, recency) unaddressed, though those are named in the schema.

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

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

Schema coverage is 78%, but the description still adds meaning the schema does not: it clarifies the query/filter split ('location, work mode, seniority and skills go in their filters, never in the query'), demonstrates OR and `title:` usage, and explains when to enable `semantic` versus relying on keywords. Undocumented parameters such as `salary_min`, `visa_sponsorship` and `posted_within_days` get no treatment in the description.

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

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

Opens with a specific verb+resource+corpus: 'Search freehire's catalogue of IT job postings,' then narrows scope with 'Use for any question about which jobs are open — by technology, seniority, location, pay or employer.' That scoping distinguishes it from siblings like search_companies, job_market_stats and similar_jobs, which cover different resources.

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

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

Explicit routing rules: free-text names go in `query`, while 'Location, work mode, seniority and skills go in their filters, never in the query,' and `semantic` is reserved for need-in-words queries rather than job titles. It also gives a recovery procedure when results are thin ('loosen one constraint at a time and say which') and an OR-joining tip for synonymous titles.

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/not destructive/openWorld, so the safety profile is covered. The description adds real behavior beyond them: result ordering (nearest first) and the empty-result edge case for recently added postings. It still leaves ranking method and result shape unstated.

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?

One tight sentence front-loads the core operation, then the ordering, then the edge case in a short trailing clause. No filler, and the most important information comes first.

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, and it does cover the one non-obvious behavior (empty results for newest postings). The only gap is that it never clarifies what 'limit' defaults to or how ties in similarity are ordered.

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

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

Schema description coverage is 100%, so both slug and limit are already documented in the schema. The description only echoes that matching is done 'by its slug' and adds nothing about the limit or ordering semantics of the returned set.

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

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

States a precise operation and resource: postings most similar to one given posting. The ordering clause 'nearest first' and the 'show me more like this' framing mark it as a similarity/recommendation tool, cleanly separating it from search_jobs (query-driven) and get_job (single-posting fetch).

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 clear use case ('show me more like this') and a practical caveat that results are empty for the newest postings. It does not name an alternative tool or state an explicit when-not-to-use rule, so it stops short of the top band.

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?

Well beyond the annotations, it discloses that delivery goes to the account's connected channels rather than this conversation, that invalid vocabulary values are dropped and reported in ignored_params, how the default channel is resolved, and that 'nothing existing is changed'. It also states the alert.id returned becomes the addressing handle for later calls.

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

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

The scope and delivery model are front-loaded before the example, and nearly every sentence carries information. Some clauses are dense and em-dash-heavy, and the trailing 'Effect:' sentence partially restates what precedes it.

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 6-parameter tool with a 35-facet nested object and no output schema, the description covers the create-vs-reuse effect, the channel defaults, the ignored-value behavior, and the returned alert.id. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still adds real meaning: a fully worked filters example, the rule for salary_min currency pairing with filters.salary_currency, and the channels default behavior. The filter vocabulary source (facets tool) is only referenced indirectly through 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 opens with a precise verb+resource ('Create a job alert: a saved search over ANY of the job search's filters') and immediately defines the delivery semantics. It is clearly distinguishable from siblings like list_subscriptions, update_subscription, unsubscribe, and subscription_updates.

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

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

It gives concrete usage conditions: the search must narrow the catalogue, empty channels falls back to a defined default, and an existing equivalent search is reused rather than duplicated. It does not explicitly name the sibling used to remove or modify an alert, so the exclusion guidance is implied rather than stated.

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 and destructiveHint=false, and the description reinforces that with 'Effect: none, read-only.' Beyond that it adds real behavioral context: matching runs every few minutes, a newly created alert starts empty, and 'delivered' indicates whether an alert already carried the posting. Missing only pagination/limit behavior and total-count semantics, which keeps it at 4.

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

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

Five compact sentences, front-loaded with what the tool returns, then filters, then behavioral caveats. Dense but each sentence carries information; the 'Effect: none, read-only' line is slightly redundant with readOnlyHint but is short enough not to waste 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?

With no output schema, the description does well to explain 'delivered' and to characterize the returned set (newest first, still-open only), which is what an agent needs to interpret results. It is silent on the response shape beyond that and on what limit 50 truncation implies, a small gap for a list tool with fully documented parameters.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including defaults, maxima, and the since-overrides-days rule. The description repeats the id/since/days narrowing but adds little to the schema beyond the matching-window semantics tied to id; the limit parameter is not mentioned at all in the prose, so the 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?

Opens with a specific verb and resource: 'List the new postings the person's job alerts have matched,' and adds scope ('still-open postings only, newest first'). The clause 'the same matches their alerts are built from' implicitly separates it from list_subscriptions, but no sibling is named explicitly, so it lands just short of full 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?

It explains how to narrow results (one alert by id, a window by since or days) and the caveat that an alert only matches postings appearing after its creation, which is genuine usage context. However, it never states when to reach for this instead of search_jobs, my_jobs, or list_subscriptions, leaving alternative selection to inference.

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

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

Beyond the annotations, it discloses dedup behavior ('repeated requests share the existing queue entry and increase request_count'), refusal of existing terms and aliases, and the meaning of status. These are non-obvious side effects that an agent could not infer from readOnlyHint=false / idempotentHint=false alone.

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

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

The most important constraint (records a suggestion, not a filter) is front-loaded, and each sentence carries distinct rules. It is somewhat dense with long compound sentences and an awkward clause ('as on freehire's dictionary page'), which costs a point on readability.

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 no output schema, the description covers the outcome (a queued suggestion with a review status), the dedup side effect, and the user-facing message. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is a 3; the description adds meaning by specifying the term should be 'the user's original term' sent 'once per missing term' without a separate prefetch. It does not elaborate further on the kind enum beyond what the schema already documents.

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 ('Request review of a missing specialization, skill or company industry') and immediately disambiguates it from siblings: 'This records a suggestion, not a new working filter or a vacancy.' An agent can tell this apart from search/list/filter tools 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 when-to-use is given ('a specialization, skill or industry the user wanted to filter by but the dictionary cannot resolve') along with an exclusion ('an empty job search alone is not evidence of a missing term'). It also tells the agent what to say to the user, removing guesswork about downstream messaging.

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=false, and readOnlyHint=false, so the agent knows this mutates state; the description usefully adds partial-update semantics for the omitted-field case. It does not disclose the consequences flagged by destructiveHint — e.g., whether an existing note is overwritten rather than appended, or whether changing stage discards prior stage history.

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 action and followed by the partial-update rule and the enum. The enum list is somewhat redundant with the schema, but it is compact and does not bloat the definition.

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 three-parameter mutation tool with no output schema, the description covers the action, the optionality of fields, and the stage vocabulary. It leaves open what the call returns and whether a tracking record must pre-exist, which are the main remaining gaps for an agent invoking it unsupervised.

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

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

Schema coverage is 100%, so all three parameters are already documented and the stage enum is fully enumerated in the schema; restating the valid stages in the description adds little beyond that. The one genuine addition is the omit-to-leave-unchanged rule, which clarifies that both mutations are optional and independent.

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 ('Set the application stage and/or a free-text note') and scopes it to 'a vacancy the user is tracking,' which separates it from generic mutation siblings like save_job or apply_job. It stops short of explicitly naming which sibling to use for adjacent actions, so it is clear but not fully differentiated.

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 line 'Omit a field to leave it unchanged' gives useful partial-update guidance for the two optional fields. However, there is no statement of when to use this versus apply_job, save_job, or my_jobs, and no preconditions (e.g., whether the job must already be tracked or whether an unrouted slug creates a tracking entry).

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?

The annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=true, so 'Idempotent' in the description is a restatement rather than added value. It omits genuinely useful behavior: whether removal requires authentication, and what happens if the vacancy was never bookmarked (no-op vs error).

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 the action front-loaded and no filler. The second sentence duplicates an annotation and so does not fully earn its place, but the overall size is well matched to the tool's simplicity.

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 bookmark removal, annotations cover the safety and idempotency profile and the schema covers the identifier, so little is left for the description to carry. The only real gap is the not-currently-bookmarked case and any authentication requirement.

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 parameter with 100% schema description coverage, where slug is documented as the vacancy's public_slug. The description adds nothing about the identifier, which is acceptable when the schema already carries it, 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: 'Remove a vacancy from the user's bookmarks.' An agent can immediately tell this is the inverse of save_job. It does not explicitly name the sibling save_job, which keeps it 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?

The usage is implied by the inverse phrasing of the sibling save_job, but the description never says when to prefer this over alternatives or what precondition must hold (e.g., the job must currently be bookmarked). No exclusions or routing guidance are provided.

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 flag destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description still earns credit by disclosing the concrete blast radius: the delivery and match records for the affected channels are deleted while the saved search persists — a material fact not present in any structured field. It could go further on irreversibility or behavior when the alert is already stopped.

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?

One sentence, front-loaded with the action and id, followed by the effect and the persistence caveat. No filler and nothing buried.

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 destructive tool with full schema coverage and no output schema, the description covers action, scope, deletion effect, and what survives — everything needed to invoke it correctly and without surprise.

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 both parameters are documented, including the enum of channels and 'Omit for all'. The description's 'on every channel or on the one named' restates the schema rather than adding syntax or format meaning, so 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 and resource ('Stop one job alert by its id') and scopes the operation to every channel or a single named one, so an agent can distinguish it from subscribe/update_subscription. It stops short of naming a sibling explicitly, which keeps it from 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?

Usage is implied rather than stated: 'Stop one job alert' plus the note that the saved search itself remains as a bookmarked search tells the agent what this tool does and what it is not for. There is no explicit when-to-use versus alternatives guidance — e.g., whether update_subscription should be preferred to pause rather than stop an alert.

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 flag destructiveHint=true and non-idempotent behaviour, but the description adds substantial detail beyond them: patch semantics where omitted fields are untouched, the exact clearing rules (empty filters object, salary bound of 0), that added channels must be connected, and that a removed channel's match history is destroyed. It also discloses a scope boundary the agent would otherwise guess at — digest timing is account-wide and not changed here.

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 operation and its partial-update rule are front-loaded in the first sentence, followed by field-by-field rules, an example, and an effect statement. It is dense and every element is useful, but the closing "Effect:" sentence partly restates overwrite semantics already covered earlier, and the long parenthetical about filters is harder to scan than a short list would 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 destructive, nested-schema mutation with no output schema, the definition covers what an agent needs before calling: required id, optional-only-changes behaviour, how to reset values, what is preserved (website-only `other` filters), what is silently dropped and reported, and the destructive consequence of channel removal. Only the return shape of ignored_params is left implicit, which is minor.

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

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

Schema coverage is 100%, so the schema alone would justify a 3, but the description meaningfully exceeds it: it defines replacement semantics per filter family, clarifies that channels is the complete set rather than an increment, explains the 0-clears convention for salary bounds, and points to the facets tool as the source of valid filter values. The worked example payload concretely ties filters, salary_min and salary_currency together.

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

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

The description opens with a specific verb and resource, "Change one of the person's job alerts by its id", which lets an agent distinguish this mutation from siblings like subscribe, unsubscribe and list_subscriptions. It stops short of naming those siblings explicitly, so the boundary between creating an alert and updating one is implied rather than stated.

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 clear: this targets an existing alert identified by id and applies partial updates. It also gives practical steering on how to express a search (including a worked example) and notes that unknown values are dropped and returned in ignored_params. There is no explicit when-not or named alternative tool for creating/replacing alerts, which keeps it out of the 5 band.

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