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

Description adds 'Idempotent' but this is already declared in annotations via idempotentHint=true. No additional behavioral context like authentication requirements, side effects, or error conditions. With annotations present, the description adds minimal value.

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 fluff. Every word earns its place. Exceptionally concise and to the point.

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 tool with one parameter and no output schema, the description covers the essential purpose and idempotency. Could mention the return behavior (e.g., success/failure indicators) but not strictly necessary given the tool's simplicity.

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?

Single parameter with full schema coverage (description in schema). Description adds no extra meaning beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

Clearly states the verb 'Mark' and resource 'job', and mentions idempotency. Could be more specific about the effect (e.g., creating an application) but overall clear. No differentiation from siblings like 'submit' or 'save'.

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 guidance on when to use this tool vs alternatives. Does not explain prerequisites (e.g., must be authenticated) or when not to use (e.g., if already applied). The only behavioral note is idempotency, which is already annotated.

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, so the safety profile is covered. The description adds useful behavior beyond that: a 50-slug batch limit and the possible per-posting outcomes (open, closed, not_found) including closure timing or last-seen-live information.

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 tightly written sentences with no waste. The core action and batch limit are front-loaded, followed immediately by the workflow guidance and return semantics.

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-only check with no output schema, the description provides enough: what it checks, the batch limit, when to use it, and what each posting response can contain. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that the slugs are the public_slug values returned by search results, which goes beyond the schema's generic 'Posting slugs' label.

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. It identifies the slug source (public_slug carried by search results) and distinguishes this from search or job-detail tools by focusing on open/closed/not_found status.

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 clear usage context: use before presenting a shortlist or acting on a saved one. It does not explicitly name an alternative tool or exclusion, but the timing guidance is strong enough for an agent to know when this belongs in a workflow.

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; the description adds that the tool also returns open jobs beyond the company info. It does not mention pagination or data limits, but for a simple fetch this is acceptable.

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

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

A single, front-loaded sentence that earns its place with no filler. Every word adds meaning.

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

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

For a simple retrieval tool with one parameter and no output schema, the description provides sufficient high-level information. It does not detail the output structure, but that is acceptable given the tool's simplicity.

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 parameter 'slug' is described in both schema and description. The description reiterates the role of slug ('by company slug'), adding no new semantic detail beyond the schema.

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

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

The description clearly states the verb ('Fetch'), the resource ('a company and its open jobs'), and the method ('by company slug'). It distinguishes from sibling tools like 'job' and 'search' by specifying the combined 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?

The description implies usage when a company slug is available and one wants company details plus open jobs, but it does not explicitly compare with siblings or state when not to use it. Absence of usage guidance is a gap.

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the load and does so well: it explains duplicate handling (existing posting returns its slug), page-readability fallback (imported into catalogue), and uncrawled boards (queued for onboarding). It omits auth requirements and rate limits, which are the remaining behavioral gaps for a write-intake 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?

Four tight sentences, front-loaded with the purpose, followed by outcomes, the status enumeration, and the follow-up sibling. Every sentence adds distinct information with no repetition of the schema 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?

There is no output schema, so the description must explain returns, and it does: it enumerates the possible status values (found, tracked, imported, review, queued) and states that an existing posting yields a slug. For a one-parameter intake tool this is complete enough to call correctly and interpret the result.

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% for the single url parameter, so the baseline is already met. The description adds real meaning beyond the schema by clarifying that the URL may be either an individual job posting or a whole company career board, which changes what the agent should supply.

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 (hand over/contribute a link) and the exact resources accepted: a vacancy posting or an ATS company career board. It also distinguishes itself from the sibling my_contributions, which is named as the way to check previously sent links.

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?

Makes clear this is the same intake used by the website and CLI, so the agent knows it is the canonical submission path, and it names my_contributions as the follow-up tool. It stops short of explicit when-not-to-use guidance (e.g. do not re-send links already tracked), but the context is clear.

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, so safety is covered. The description adds genuinely useful behavior: the data is cached analysis, and the missing_have vs missing_gap split prescribes what to do with each (reframe existing evidence vs ask the candidate) — actionable context an agent could not infer from structured fields.

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

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

A single dense sentence enumerating the returned content, followed by a short imperative. Front-loaded and free of filler, though the packed parenthetical makes it heavier to parse than necessary.

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?

No output schema exists, and the description compensates by naming the key fields returned plus the interpretation each requires. The only gap is not stating the response shape or whether context may be absent when no tailoring exists.

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 100% schema coverage the single id parameter is fully documented in the schema, including its provenance and the warning never to construct one. The description adds nothing about the parameter, 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: shows the cached fit-analysis context for a tailored CV, and enumerates its contents (verdict, recommendation, dimension comments, requirement split). This clearly separates it from cv_get (CV content) in spirit, though it never names the sibling 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?

"Read this before editing" gives a concrete usage trigger tied to the editing workflow. It stops short of naming alternatives (cv_get, cv_tailor) or stating when not to call it, so it's clear context rather than 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 only declare readOnlyHint=false, so the description carries the load and does so richly: atomicity ('one uncited op rejects the whole batch'), server-enforced refusal of PII fields, the evidence_id requirement, and the 422-on-bad-path contract with the CV left untouched.

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 core action and prerequisite, then the constraint wall, then the escape hatch (cv_render). The 'THE HONEST WALL' framing is stylized but the content under it is dense and non-redundant; a slightly cleaner register would earn 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?

For a mutation tool with no output schema, it covers prerequisites, error semantics, and the evidence contract well. It does not say what a successful batch returns (result shape, counts, whether a new CV revision id comes back), which is the one gap given no output schema exists.

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 a baseline 3 applies, but the description adds genuine meaning beyond the schema: it explains that path indices are counted over the document cv_get returned and reinforces that evidence_id backs any claim of what the candidate did. The note parameter is not elaborated, which keeps it short of a 5.

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

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

States a specific verb (apply a batch of edits), resource (tailored CV), and a distinguishing trait (path-addressed, atomic). An agent can differentiate it from cv_tailor, cv_get, and experience_* tools immediately.

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 prerequisites (read cv_context and cv_get first, because indices are counted over cv_get's output), a routing rule for missing_have vs missing_gap, and a pointer to cv_render for export. Alternatives and conditions are named rather than inferred.

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, so the safety profile is covered; the description adds value beyond them by disclosing what the payload contains (header, summary, experience bullets, skill groups). It does not mention format, rendering, or failure behavior for a missing id.

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

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

A single front-loaded sentence with no filler; the parenthetical of returned sections earns its place by telling the agent what it gets back.

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 usefully sketches the response shape, and the readOnly annotation covers safety for a one-parameter read. Only the missing guidance relative to sibling CV tools keeps it from being complete.

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 explains the id, its provenance, and that it is opaque. The description adds nothing about the parameter, 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 ('Fetch a tailored CV') and enumerates the returned document sections, which distinguishes it from the list-oriented cv_list. It does not explicitly name any sibling to contrast with, so it stops 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 word 'tailored' plus a single required id implies retrieving one already-generated CV, but the description never says when to use this instead of cv_list, cv_context, or cv_edit. Usage is inferable 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=true, so safety is covered; the description adds non-obvious behavior — sort order (newest edit first) and that each item is paired with its target vacancy. It doesn't state whether results are scoped to the caller only or how large the list can get, which would have made it 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, both front-loaded with the highest-value facts (what it returns, then how to use it). No filler or restatement of the tool 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?

With no output schema, the description carries the burden of describing the return value, and it does: ordered list of CVs, each annotated with the vacancy it targets. Combined with the annotation for safety, an agent has everything needed to call this correctly.

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

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

The tool takes zero parameters, so the baseline is 4; there is no argument semantics left to explain and the description correctly presents the call as argument-free.

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

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

States a specific verb and resource (list the caller's tailored CVs) plus the ordering (newest edit first) and payload shape (each with the vacancy it was written for). This clearly separates it from cv_get, which retrieves one CV by id.

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 two concrete use cases: discovering the id required by the other cv_* tools, and checking whether a vacancy already has a tailored copy. It implies rather than states the exclusion ('don't call this if you already have the id'), so the routing is clear but not fully enumerated.

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?

With only readOnlyHint/idempotentHint annotated, the description carries the important behavioral payload: the return is a base64 resource of type application/pdf, the bytes are large, and they are not model-readable. That last point is exactly the kind of operational warning an agent cannot get from structured fields.

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

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

Two sentences, zero filler, with purpose and output format front-loaded before the anti-use caveat. Every clause earns its place.

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

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

For a single-parameter render tool with no output schema, the description supplies the missing return-value story (base64 PDF resource, large payload) and warns against introspection — nothing an agent needs before calling is absent.

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

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

Only one parameter, and the schema description already covers it fully (source via cv_tailor/cv_list, URL form, 'never construct or guess'). The description adds nothing about the id, so this sits at the 100%-coverage baseline.

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

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

States a specific verb and resource: 'Render a tailored CV to an ATS PDF,' which unambiguously differs from cv_tailor (produce the CV) and cv_get (fetch the CV). It never names those siblings explicitly, so an agent must infer the boundary rather than being routed to it.

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 to produce the deliverable, not to inspect content' gives an explicit when-to-use and a clear when-not-to-use, with the inverse (inspection) implied toward cv_get/cv_context. It stops short of naming the alternative tool for the inspection case.

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

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

Annotations only supply readOnlyHint=false; the description adds substantially more: idempotent-per-slug semantics, a one-AI-credit cost on first creation, a 402 on insufficient balance, and a 409 when the candidate has no seed résumé. It also clarifies the tool performs no model call, setting the agent's expectation about what work remains.

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 dense sentences with zero filler: purpose+return first, then idempotency, then cost/error behavior, then the boundary against cv_context/cv_edit. The most decision-relevant facts (idempotency, credit spend) are front-loaded.

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

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

There is no output schema, and the description compensates by enumerating the returned fields (id, base, session). Combined with the cost, error-code, and prerequisite coverage, an agent has everything needed to call it correctly and to handle failures.

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 job_slug parameter is fully documented in the schema (public slug from search or facets results). The description reinforces the per-vacancy/slug scoping but adds no syntax or format detail 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?

Opens with a specific verb+resource ("Start tailoring a CV to a vacancy") and immediately states what is returned (tailored CV id, base copy, bound session). It also differentiates itself from cv_context and cv_edit by declaring it does not call a model, so an agent can distinguish it from the reframing siblings without opening their 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?

Gives an explicit safe-call rule ("calling it again for the same slug reopens the copy that already exists, so it is safe when you do not know whether one exists") and routes follow-up work to cv_context and cv_edit. It also names the prerequisite failure path (409 when no résumé exists, tell them to upload one; you cannot), which is genuine 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?

Goes well beyond the lone readOnlyHint=false annotation: it discloses the server-side `manual` provenance stamp and why it matters (CV citability), and documents the 409 duplicate-refusal behavior keyed on spelling. That is exactly the kind of side effect and failure mode an agent needs before calling.

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

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

Three tight sentences, front-loaded with the core action before the provenance rule and the dedup/409 escape hatch. Slightly dense in the second sentence but 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?

Given full schema coverage and no output schema, the description covers purpose, provenance, and the duplicate case well. The only gap is that it doesn't say what a successful call returns (e.g., the created record id), which leaves a small amount for the agent to discover.

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 already 100%, so the schema documents all five parameters. The description reinforces the `claim` semantics but adds nothing about skills, metrics, context, or employment_id beyond what the schema states; 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?

Specific verb and resource ('Record one piece of evidence'), with the payload shape made concrete as 'the sentence a CV bullet would carry'. It is clearly distinguishable from the neighboring experience_update_achievement and experience_add_employment tools.

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 'only record what the CANDIDATE told you' constraint plus an explicit alternative: if the claim already exists, use experience_update_achievement instead of re-adding. Both the when and the when-not are 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?

The annotations only declare readOnlyHint=false, so the description usefully adds the key validation rule (at least company or role, despite required=0 in the schema) and the fact that the call returns an id consumed downstream. It does not disclose whether duplicate employers are merged or rejected, which matters for a mutation tool, so it stops short of 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 short sentences, zero filler: the first defines the resource, the second states the requirement and the follow-up workflow. The critical constraint is front-loaded after the identity sentence.

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 8 optional parameters, no output schema and minimal annotations, the description does the important work: it explains the create semantics and tells the agent the response yields an id for chaining. It could go further on update/duplicate handling, but nothing essential for a correct first call 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%, including the enum for kind and date formatting for start/end, so the schema already carries parameter meaning. The description adds one cross-field constraint (company-or-role) that the schema cannot express, but otherwise leaves semantics to the schema. Baseline 3 is appropriate.

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

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

The description pairs a specific verb ("Record") with a concrete resource (a job or side project where evidence was produced) and names the two kinds via the schema's enum. It is clearly distinct from experience_add_achievement, which it references, though it never contrasts itself with experience_update_employment, leaving the create-vs-update boundary implicit.

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 next-step chain: call this, then use the returned id with experience_add_achievement to attach achievements. It also states the minimum requirement (at least company or role). What's missing is guidance on when to prefer experience_update_employment over this tool, or how to handle duplicates.

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

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

Annotations only declare readOnlyHint=true; the description adds the substantive behavioral rule that PROVENANCE determines citability, and names which values (cv_import, stated_in_chat, manual) may be cited versus agent_inferred, which may not. That is real safety-relevant context beyond the annotation. It does not mention volume/size of the bank or any pagination behavior, so it stops short of 5.

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

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

Three sentences, front-loaded with what is read, then the provenance rule that governs downstream use, then the cv_edit hand-off. It is dense but every clause carries information. Minor deduction for the shouty "PROVENANCE" and backticked identifiers, which slightly impede scanning.

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

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

With no output schema, the description does the work of describing the return structure: employments, their nested achievements, the `unplaced` bucket, per-achievement provenance, and the evidence_id field. That covers what an agent needs to consume the result. A note on whether achievements are ordered or how large the payload typically is would close the remaining gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description instead spends its words on output semantics, which is the right allocation.

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?

"Read the candidate's whole experience bank: every employment and the achievements attached to it, plus the ones attached to no place under `unplaced`" pairs a specific verb with a specific resource and the exact shape of what's returned. It is clearly distinguishable from the experience_add_*/update/remove siblings, which mutate, and from cv_get, which reads a rendered CV rather than the underlying bank.

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?

"Take evidence_id for cv_edit from here" explicitly routes the agent to the downstream sibling and states the precondition for using it. It does not, however, state when NOT to call this (e.g. when cv_context would be preferred, or whether a fuller profile read exists), so the exclusion side is only 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 flag destructiveHint=true, but the description adds genuinely new behavioral facts: the operation is irreversible ('no undo'), it is scoped so it 'takes nothing else with it', and there is a confirmation protocol before execution. That is exactly the context an agent needs before invoking a destructive 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?

Front-loads the destructive action in the first clause, then layers on irreversibility, confirmation, and duplicate resolution in a logical order. Four short sentences with no filler, though the duplicate example is slightly more anecdotal than the rest.

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

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

For a one-parameter destructive tool with no output schema and strong annotations, the description covers irreversibility, scope, and the pre-call confirmation step. Minor gaps remain: no statement of what the response looks like or whether the id is validated before deletion.

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 `id` parameter is documented in the schema, including its provenance from experience_list and its equivalence to cv_edit's evidence_id. The description adds nothing about the parameter, which is acceptable at full coverage but is baseline rather than value-adding.

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: 'Delete one achievement from the bank', with the 'one' making single-item scope explicit. The resource name distinguishes it in practice from experience_remove_employment, but the description never names that sibling or any other, so differentiation is left to the reader comparing names.

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 precondition (confirm with the candidate, read it back, act only on a clear yes) and a concrete use case (resolving duplicates by keeping the richer entry). It does not cover the obvious alternative of correcting an entry via experience_update_achievement rather than deleting it, so the when-not is only partially addressed.

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

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

Goes well beyond the destructiveHint annotation: discloses the cascading consequence (everything recorded under it would be deleted), the 409 refusal behavior, and irreversibility ('There is no undo'), plus a confirmation step with the candidate. This is exactly the context an agent needs before an irreversible mutation.

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 constraint and the consequence, then the remediation workflow. Slightly undercut by the inconsistent 'place/bank' wording, but every sentence carries real content.

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

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

For a single-parameter destructive tool with no output schema, the description covers precondition, failure mode, remediation path, and irreversibility. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and the id parameter already documents origin (experience_list) and opacity. The description adds no additional format or lookup guidance beyond that, 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+resource: deleting an experience entry that must be empty. The mechanics are clear, though the vocabulary mismatch ('place from the bank') against the tool name and schema field ('employment id') adds avoidable ambiguity that the later sentences only partly resolve.

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

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

Explicitly states the precondition (must hold no achievements), what happens if violated (server refuses with 409), and the alternative workflow: move achievements with experience_update_achievement, then remove the empty shell. It names the sibling tool directly, so there is no guesswork.

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

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

Annotations only supply readOnlyHint=false, so the description carries the weight and does well: it discloses partial-update semantics ("Only the fields you pass change"), destructive list replacement for metrics/skills, and the immutable-provenance rule (agent_inferred stays agent_inferred and uncitable). It stops short of stating error behavior or whether a correction is reversible/logged.

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 core purpose, then the partial-update rule, then the provenance caveat that prevents a common misuse. Four sentences, each carrying a distinct decision-relevant fact, with no redundancy.

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 mutation tool with only readOnlyHint=false for annotations and no output schema, the description covers the remaining gaps: what changes, what is destroyed, and what stays fixed. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real signal by stressing that metrics and skills REPLACE wholesale rather than merge, which is the riskiest parameter behavior. It does not clarify employment_id as a move operation beyond what the schema already says.

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

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

Specific verb+resource: "Correct an achievement already in the bank," with an immediate distinction from the add path ("cannot be fixed by re-adding it"). An agent can tell this apart from experience_add_achievement and experience_update_employment without inspecting schemas.

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

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

Names the primary trigger (a typo in the claim), rules out the tempting alternative (re-adding), and spells out the only valid path to change citation status (confirm with the candidate, then record what they said). This is explicit when/when-not/alternative guidance.

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

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

Annotations only declare readOnlyHint=false; the description earns its keep by disclosing the non-obvious PATCH semantics — omitted fields are preserved from the banked row despite the API replacing the whole row. That is exactly the trap an agent would fall into. It does not mention permission or auth requirements.

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, zero filler. The core identity ('correct a place') comes first, the critical partial-update behavior second, and the concrete use case last. Every sentence carries distinct 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 nine-parameter mutation with full schema documentation and no output schema, the description supplies the one thing structured fields omit — merge-vs-replace semantics. A brief note on the response or on the failure mode when the id is unknown would make it complete.

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 would be 3, but the description adds meaning the schema does not: that this is a merge-style update where unspecified fields carry over. Without that, an agent could wrongly assume omitted fields are cleared, which matters for all nine parameters.

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

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

States a specific verb+resource ('Correct a place already in the bank') and the tool name confirms it is an employment record. It distinguishes itself from the add/remove siblings by framing this as correction, but 'place' and 'the bank' are soft wording that doesn't literally name the employment record.

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

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

'Use this to fix a name, a role, or dates' gives a clear when-to-use condition with concrete examples. It does not explicitly point at experience_add_employment or experience_remove_employment as alternatives for non-correction cases, which is the remaining gap.

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

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

Goes well beyond readOnlyHint=true by disclosing the API's silent-failure semantics: unknown filter keys are ignored rather than refused, results come wrapped as {data, ignored}, and unknown values return in `ignored_values` (with a worked example). It also gives the corrective action for each case, which is exactly the operational context annotations cannot carry.

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, each load-bearing: purpose first, then call-order guidance, then the two silent-failure modes with their remedies. No restatement of the name or filler.

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

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

With no output schema, the description does the work of describing the return payload (facet values with counts, skills list, numeric ranges, and the {data, ignored} / ignored_values wrappers). The one gap is the unexplained 14-parameter signature on what is nominally a read-only vocabulary listing, which an agent may find puzzling.

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 14 filter parameters are already fully documented in the schema and the baseline is 3. The description adds only indirect value by pointing at where valid facet keys and values come from; it says nothing about the individual parameters or why a discovery tool accepts search filters at all.

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

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

States a specific verb and resource: 'List the market's filter vocabulary' with concrete contents (live facet values, vacancy counts, skills list, numeric ranges). It is clear what the tool returns, but it never distinguishes itself from the sibling `list_filter_values`, which reads as a near-duplicate — an agent has no textual basis for choosing between them.

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: 'Call this FIRST to discover real values for `search` and `market_fit` — do not invent facet values', naming both downstream consumers and the anti-pattern. No exclusion against the similar `list_filter_values` sibling, so the routing is strong but not complete.

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

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

Annotations already show readOnlyHint=true, so the agent knows this is a safe read. The description adds value by listing the fields returned (title, company, location, posting URL, description), providing behavioral specifics beyond annotations without contradiction.

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

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

The description is a single sentence, 14 words, with the verb and key action front-loaded. Every word serves a purpose, and there is no redundant or filler content.

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

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

With only one parameter and no output schema, the description adequately covers what the tool does and what it returns. It does not mention error handling or slug existence, but for a simple fetch-by-id tool, this is sufficient and not a significant gap.

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

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

Schema coverage is 100% and already describes the slug parameter as 'The job's public slug (from search or facets results).' The description merely repeats 'by slug' without adding any new semantic detail, 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?

The description clearly uses 'Fetch' as the verb, specifies the resource as 'a single job', and identifies the key identifier 'slug'. It also enumerates the returned content fields, distinguishing this from sibling tools like 'search' which return lists, and 'apply', 'save', etc. which perform other actions.

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

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

The description implies usage when a slug is available (e.g., from search or facets results) and provides clear context for retrieving full job details. However, it does not explicitly state when not to use this tool or name alternatives, leaving some room for 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?

readOnlyHint=true already covers the safety profile, and the description adds genuinely non-obvious behaviour: unrecognised filter values are silently dropped but echoed back in the answer, with an instruction to correct them before reporting numbers. It stops short of disclosing aggregation limits, default scope with zero filters, or cost/latency for a 20-parameter query.

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 returned-facet list is front-loaded so an agent immediately knows the shape of the answer, and the second sentence carries a single actionable 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?

With 20 optional parameters, no output schema, and only readOnlyHint for annotations, the description does well to enumerate what the response contains, which is the biggest gap it could have filled. Missing are the no-filter default (count everything?), any cap on returned facet values or result size, and ordering of the distributions.

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 80% and most filters carry their own examples and enumerations (skills, regions, seniority, work_mode, relocation, employment_type, CEFR levels), so the schema does the heavy lifting. The description adds only the cross-cutting rule that invalid values are dropped rather than erroring, and says nothing about the four undescribed parameters (salary_min, salary_currency, visa_sponsorship, posted_within_days).

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 (count) plus a resource (open postings matching filters) and enumerates the facets returned (role families, seniorities, skills, work modes, countries, regions). It is clearly an aggregation tool rather than a listing tool, but it never names siblings like `search`, `salary_stats`, or `facets`, so the differentiation is inferred 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 is only implied: the mention of quoting a figure suggests analytics/reporting use, and the warning to fix unrecognised values implies an iterative filter-refinement workflow. There is no explicit when-to-use versus `search` (posting-level results) or `salary_stats` (compensation distributions), and no stated 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?

Discloses key behaviors: URL as dedup key (idempotent update), description stored as HTML, and auth requirement. Annotations already indicate idempotentHint, but description adds how idempotency is achieved.

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 with front-loaded purpose. No redundancy, every sentence provides unique value.

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

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

Lacks return value information despite no output schema. Otherwise covers purpose, behavior, and auth. Moderate complexity with 3 required params.

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 75% schema coverage, description adds meaning for critical params: 'url' dedup key and 'description' HTML storage. Other params are sufficiently described in 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?

Description clearly states 'create a hand-curated job' with specific verb and resource. Distinguishes from sibling 'jobs_edit' and others via dedup key behavior and moderator role.

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

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

Explicitly states 'Requires the moderator role (403 otherwise)' indicating when to use. No explicit alternatives mentioned, but the context of hand-curated and sibling list provides implicit 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 show readOnlyHint=false and idempotentHint=true. The description adds critical context: partial update semantics and 403 error for non-moderators. This exceeds what annotations alone provide.

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, each adding unique value: purpose + constraint, then role requirement. No redundancy or fluff.

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 7 parameters and no output schema, the description is minimal. It explains partial updates and role requirement but omits side effects, success response, or distinction between manual and other jobs. Could be more complete.

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 43%, so the description should compensate. It adds context for the slug parameter (not editable) and general partial update behavior, but does not elaborate on other parameters beyond schema descriptions. Adequate but not rich.

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 'Moderator: partially update a manual job by slug', specifying the action (update), resource (manual job), and identifier (slug), clearly distinguishing it from sibling tools like 'jobs_add'.

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

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

The description clarifies partial update behavior and role requirement ('Requires the moderator role'), but does not explicitly compare with alternatives (e.g., 'jobs_add' for creation). The implication is present but not explicit.

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, so safety is covered. The description adds genuinely non-obvious behavior: results are sorted most common first, each value carries a count of open postings, and 'a value not listed matches no posting' — a crucial negative guarantee an agent cannot get from the schema.

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

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

Two sentences, front-loaded with what is returned and how it is ordered, then usage. Every clause earns its place — the value set, the counts, the sort order, the no-match guarantee, and the two usage triggers.

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, and the description compensates fully by describing the shape of each returned value (value + open-posting count) and its ordering. Combined with the coverage-complete input schema and the readOnly annotation, an agent has everything needed to call 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?

Schema description coverage is 100%, so all three parameters (filter, limit, contains) are already documented, including the enum-like list of filter names and the alias behavior of contains. The description's enumeration of filter kinds restates the schema rather than adding new meaning. 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 states a specific resource and scope: the accepted values for one job-search filter, each with posting counts, ordered by frequency. An agent can tell this is a lookup tool rather than a search tool. It stops short of naming the closest sibling (facets), so the boundary with facet-style counting tools is left to inference.

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: 'Use it before filtering on a value you are not sure of, and to fix one a search reported in ignored_values.' This ties the tool to a concrete workflow hook (ignored_values) rather than leaving usage implied. No when-not guidance or named alternative is offered, keeping it below 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?

The readOnlyHint already establishes that this is a safe read operation, and the description adds useful behavioral detail about the returned fields, delivery channels, pending matches, last delivery, and the account-wide delivery_schedule. It still omits details such as ordering or whether all alerts are returned in one response, but it meaningfully exceeds what annotations provide.

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 front-loaded with the main action and then enumerates return fields, so every part is relevant. It is a dense single sentence with parentheticals, which slightly harms readability, but it avoids unnecessary 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?

There is no output schema, so the description must explain the return shape, and it does so in detail: ids, names, filter summaries, structured search objects, paused state, channel status, pending matches, last delivery, and delivery_schedule. For a zero-parameter read-only list tool, this is sufficiently complete.

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 has zero parameters, so the baseline is 4. The empty input schema is consistent with a parameterless list operation, and there are no parameter semantics that the description needs to compensate for.

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

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

The description gives a specific verb and resource: it lists the person's job alerts and enumerates the settings returned. However, it does not explicitly distinguish this from sibling tools such as subscription_updates, update_subscription, or unsubscribe, so sibling differentiation is only implied.

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 explicit when-to-use guidance, no exclusions, and no routing to alternatives like update_subscription or unsubscribe. The listing purpose is clear, but the description does not tell an agent when this tool should be chosen over related subscription tools.

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?

With readOnlyHint already covering the safety profile, the description adds genuinely non-obvious behavior: the {data, ignored, ignored_values} wrapper signals a mismatch between what was asked and what was measured, and the agent is told to fix the param and retry before quoting results. That is exactly the kind of silent-failure disclosure annotations cannot provide.

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 purpose and outputs, then the measurement-vs-filter rule, then the result-wrapper caveat — every sentence earns its place. The final sentence is terse and slightly cryptic ('measured something other than what was asked'), which costs a point on structure.

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 15-parameter tool with a nested facets object and no output schema, the description compensates well by naming the three return components and the measurement semantics. It stops short of covering result limits, skill-list size expectations, or how coverage is computed, leaving minor 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 coverage is 100%, so the baseline is 3; the description still adds real meaning by clarifying that `skills` is measured rather than filtered and that a single skill value probes that skill's demand, plus a one-skill probe use case. It doesn't add anything for the 14 facet params beyond what the schema says, so it doesn't reach 5.

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

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

States a specific verb and resource ('Score a skill list against the live open-vacancy market') plus the exact outputs produced (headline coverage, must-have skills held, missing skills unlocked). It also draws the crucial line between measuring and filtering, which is what separates it from search-style siblings.

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

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

Explicitly tells the agent that `skills` is the MEASURED set and that facet params define the role, and routes to the `facets` tool for discovering valid keys. It lacks an explicit 'use X instead when' against adjacent siblings like job_market_stats or salary_stats, so it gets a 4 rather than 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 declare readOnlyHint=true, so the description adds limited behavioral context beyond that. It mentions that the tool returns stage and note, and that filter narrows results, but does not disclose pagination behavior (offset/limit) or authentication details. For a read-only operation, this is adequate but not extensive.

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 concise sentence that conveys the main purpose. It is appropriately front-loaded but could benefit from mentioning pagination or parameter details to improve completeness without sacrificing brevity.

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 list tool with readOnly annotations and no output schema, the description covers the key aspects: what is listed (caller's tracked jobs), what fields are included (stage, note), and how to filter. However, it lacks guidance on pagination (offset/limit) which is part of the input schema, slightly reducing completeness.

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 only 33% (filter has a description), and the main description does not add meaning for limit or offset beyond what the schema provides. It mentions that filter narrows the set but does not elaborate, leaving two parameters undocumented in both schema and 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?

The description clearly states the tool lists the caller's tracked jobs (viewed/saved/applied) with stage and note, using a specific verb and resource. It is easily distinguished from sibling tools like 'my_submissions' which lists submissions.

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

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

The description implies usage for listing tracked jobs but does not provide explicit guidance on when to use this tool versus alternatives like 'my_submissions' or 'search'. No exclusions or when-not-to-use information is given.

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 that this is a read-only operation. The description adds useful domain context by defining each status value ('pending', 'review', 'onboarded', 'rejected') and clarifying that results are scoped to the caller's own contributions, though it does not discuss pagination or result ordering.

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 material. The status definitions are compact and directly relevant to interpreting the result.

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 tool, the description covers the essential behavior: what is listed, whose contributions are included, and what the status values mean. It does not describe the exact response shape, but no output schema exists and the core return semantics are still clear.

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 score is 4. There are no parameter semantics for the description to compensate for.

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

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

The description uses a specific verb ('List') and a precise resource ('vacancy and company career board links the caller has contributed'). The caller-scoped wording and the named link types distinguish it from sibling tools like contribute and my_submissions.

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

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

The description implies the tool is used to inspect the status of contributions the caller has already submitted, especially by defining the status meanings. However, it does not explicitly say when to use this tool instead of alternatives such as contribute or other listing tools.

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 description aligns with the 'readOnlyHint' annotation by stating 'List'. However, it adds no further behavioral details (e.g., pagination, sorting) beyond what the annotation already conveys.

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, efficient sentence with no extraneous words. It delivers maximum information in minimal 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?

Given the zero parameters, the readOnly annotation, and no output schema, the description sufficiently covers what the tool does and what it returns (moderation status). No 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?

There are zero parameters, so the description has no parameter details to add. The description does not need to compensate for missing schema documentation. Baseline 4 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 clearly states the action ('List'), the resource ('the caller's own vacancy submissions'), and the specific information returned ('moderation status'). It distinguishes from siblings like 'submissions_pending' or 'submission_approve'.

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

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

The description implies usage for listing the caller's own submissions, but it does not explicitly state when not to use it or mention alternative tools for different scopes (e.g., 'submissions_pending' for pending ones).

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 indicate idempotentHint=true and readOnlyHint=false, so the description does not need to reiterate safety. It adds value by explicitly stating the overwrite behavior, which is not in annotations. No contradictions.

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?

Single sentence, front-loaded with verb, no filler. Every word earns its place, making it efficient and easy to parse.

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

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

Given the simplicity of the tool (2 parameters, no output schema), the description covers the core action and overwrite behavior well. Could mention note length limits, but overall sufficient for a small 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?

Schema description coverage is 100%, providing clear parameter descriptions for 'slug' and 'note'. The description reinforces these but does not add new constraints or format details beyond the schema, maintaining a baseline score.

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

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

The description clearly states the tool attaches a free-text note to a tracked job, specifying the verb 'attach', the resource 'free-text note to a tracked job', and the distinguishing behavior 'overwrites the existing note'. This differentiates it from sibling tools like jobs_edit which modify broader job details.

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

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

The description implies usage for adding or updating notes on tracked jobs, but provides no guidance on when to use this tool versus alternatives (e.g., jobs_edit) or when not to use it. It lacks explicit context on exclusions or alternatives.

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, so safety is covered; the description adds the meaningful detail that the CV returned is 'contact-free' and that the data reflects what the candidate 'already told freehire'. It does not say what happens if no profile exists yet or whether authentication is required, which is a minor 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?

Two sentences, zero waste: the return contents come first, the usage directive second. Every clause earns its place.

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

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

With no output schema, the description carries the burden of describing return values, and it does so by enumerating the profile fields. It stops short of describing the empty/no-profile case or the shape of nested fields, but an agent has enough to call it correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly avoids inventing parameter 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?

Specific verb ('Return') plus specific resource ('the caller's saved job-search profile'), followed by an enumeration of exactly what comes back: specializations, target skills, excluded skills, location preferences, and CV. This distinguishes it clearly from identity tools like whoami and document tools like cv_get.

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

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

Explicitly directs the agent to call this 'before searching or tailoring', naming the downstream activities (search, cv_tailor) that should be grounded in its output. The sequencing rule is stated rather than implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral caveats beyond that: figures are computed only from postings that state pay, a sample size accompanies each figure, and currencies/pay periods are reported separately and never converted — real constraints an agent needs to interpret results.

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 dense sentences, no filler, and the primary output (percentiles), the source constraint, and the currency caveat are all front-loaded before any detail.

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

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

With no output schema, the description does the heavy lifting by naming the returned measures, the sample-size field, and the per-currency/per-period reporting. It is nearly complete, but omits how results are grouped when parameters are omitted and whether multiple currencies produce multiple rows.

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 country/category/seniority are already documented with examples and allowed values. The description restates that these scope the result (and hints at role-family/seniority semantics) but adds no syntax, defaults, or behavior for omitted parameters, so it sits at the baseline for high-coverage schemas.

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 concrete resource (salary percentiles at 25th/median/75th) and the exact dimensions it is scoped by (role family, seniority, country), plus a non-obvious data source constraint (only postings that state pay). It does not, however, distinguish itself from nearby siblings like job_market_stats or market_fit, leaving the agent to infer which stats tool to pick.

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

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

Usage is implied by the scoping sentence — call it when you want pay distribution for a role/seniority/country slice — but there is no explicit 'use this when… / use X instead' guidance and no mention that the three parameters are all optional, so the agent cannot tell how to get an unfiltered aggregate or when job_market_stats is the better call.

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 description mentions 'Idempotent', which is already declared via annotations. Other behavioral traits (e.g., side effects, auth needs) are not disclosed, but annotations cover the safety profile minimally.

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 wasted words. The key action and idempotency are front-loaded.

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

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

For a simple idempotent bookmark tool with one parameter and no output schema, the description is adequately complete. It could optionally mention reversal via 'unsave', but not essential.

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 describes the slug parameter well. The description adds no extra meaning about the parameter, 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?

The description 'Bookmark a job for later' uses a specific verb (bookmark) and resource (job), clearly distinguishing it from sibling tools like 'apply' or 'unsave'.

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 guidance on when to use this tool versus alternatives (e.g., 'apply' or 'unsave') is provided. The description only states the action without contextual usage.

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

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

Annotations only declare readOnlyHint, so the description carries the rest and does it well: it discloses the heavyweight result payload (full markdown description per hit), that unrecognized facet params are silently ignored, that `ignored`/`ignored_values` can make `total` answer a wider or empty question, and that geography facets OR rather than AND. These are exactly the traps that would cause a wrong answer.

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

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

Front-loaded with purpose and payload, then a clearly signposted 'How to search well' and 'Two traps' section. It is long for a description, and the region/country OR-group is explained both here and in the schema, but almost every sentence carries actionable guidance.

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

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

For an 18-parameter tool with a nested `facets` object and no output schema, the description supplies the missing pieces: the shape of each result, the meaning of `total`, the `ignored`/`ignored_values` diagnostics, and how to present output. Nothing needed to call it correctly or interpret results is absent.

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

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

Schema coverage is 100% and already documents most params, including the region/country widening caveat. The description still adds genuine guidance beyond the schema: query OR-operator practice with role synonyms, keeping location/work mode/seniority out of the query, and the ignored-param recovery loop. It loses a point only because the geography trap is partially restated from 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 opening sentence states a specific verb and resource ('Search open jobs by keyword with optional facet filters') and the follow-up names the payload shape (full description markdown, title, company, location, public_slug, total). It clearly distinguishes itself from `job` (per-hit lookup), `similar_jobs`, and `facets` (value discovery).

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: use the returned slug with `job`, `apply`, `save`; use `list_filter_values` to fix unrecognised values. It also states recovery strategy (loosen one constraint at a time and say which) and where filters belong versus the query string — no inference required.

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, so safety is covered; the description adds real value by disclosing result ordering ('nearest first') and an edge case ('Empty for the newest postings, whose neighbours are not computed yet') that an agent could not infer from the schema.

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

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

A single tight sentence with the core purpose front-loaded and the edge-case caveat appended after a dash; 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 two-parameter read-only lookup with no output schema, the description covers the purpose, ordering, and the main failure mode (empty for new postings). Only the meaning of the returned fields is left implicit, which is low-risk for a 'similar items' list.

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

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

Schema coverage is 100%, so slug and limit are already documented in the schema. The description only restates that the lookup is by slug and adds no format or constraint 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: postings most similar to a given posting identified by slug, with ordering (nearest first). This clearly separates it from generic siblings like search or job, though it doesn't name an alternative 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?

The phrase 'for "show me more like this"' implies the use case, but there is no explicit when-not guidance or named alternative (e.g., search for keyword-based discovery). The empty-result caveat is behavioral, not a usage rule.

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 indicate readOnlyHint=false (modifies) and idempotentHint=true (safe retry). The description adds the list of valid stages and mentions server validation, providing useful behavioral context beyond annotations. No contradiction.

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

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

The description is a single sentence, 17 words, with no redundant information. Every word earns its place.

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

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

The description is adequate for a simple tool with two parameters and annotations, but lacks information about return values or prerequisites (e.g., application must exist). Could be more complete to guide the agent fully.

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%, but the description adds a list of valid stages not present in the schema (which has no enums). This adds significant value by enumerating allowed values.

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 'Set' and resource 'job's application stage', and lists all valid stages, making it clear what the tool does and distinguishing it from siblings like 'apply' or 'submit'.

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

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

The description implies usage for updating an existing application's stage by listing valid values, but does not explicitly state when to use this tool versus siblings like 'apply' (new application) or 'submission_approve' (approve submission).

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

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

Adds role requirement and error code beyond annotations (readOnlyHint=false). Describes write action and outcome.

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?

Single sentence with essential info. No filler. Front-loaded with role and action.

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?

Adequate for simple action. Lacks output info or side effects, but role requirement and outcome are clear.

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 covers 100% of parameter description. Description adds context by linking id to approval action, though no extra detail on format.

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?

Clear verb 'approve' and specific resource 'pending submission' with outcome 'minting a live job'. Distinguishes from siblings like submission_reject.

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?

States required moderator role and 403 error otherwise. Implicitly indicates when to use based on pending status and role.

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 description indicates a mutation action ('reject') consistent with annotations (readOnlyHint=false), but does not disclose side effects (e.g., status change, notifications) beyond the role requirement.

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 that efficiently conveys purpose and usage without unnecessary words.

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 only two parameters and no output schema, the description covers purpose and role requirement adequately, but lacks details on return value or explicit state change.

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 description merely restates the schema's parameter details (id, optional reason) without adding new semantic information.

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

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

The description clearly states the verb 'reject' and the resource 'pending submission', distinguishing it from sibling tools like 'submission_approve'.

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 specifies the required moderator role and the error response (403) for unauthorized use, but does not explicitly mention when not to use or alternatives like 'submission_approve'.

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 description adds critical behavioral context beyond the 'readOnlyHint' annotation by specifying the authentication requirement ('Requires the moderator role (403 otherwise)'). This informs the agent about authorization constraints and error behavior.

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

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

The description is a single, concise sentence that conveys both the purpose and the prerequisite role requirement. No extraneous information is present.

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

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

Given the tool's simplicity (0 parameters, readOnlyHint annotation, no output schema), the description adequately covers purpose and auth. However, it could be enhanced by hinting at the format or content of the returned list, but this is not critical.

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 0 parameters and 100% schema description coverage, the description does not need to add parameter details. Based on the scoring rule, a baseline of 4 is appropriate since the schema already fully covers the parameters.

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

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

The description clearly states 'list the pending submission review queue' using a specific verb ('list') and resource ('pending submission review queue'). This purpose is distinct from sibling tools like 'submission_approve' and 'submission_reject', which perform actions, and 'my_submissions', which likely lists user's own submissions.

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

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

The description explicitly states the requirement for the moderator role and notes that 403 is returned otherwise, providing clear guidance on who should use this tool. However, it does not explicitly mention when not to use it or contrast it with alternatives like 'my_submissions' for non-moderators.

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 description adds context beyond annotations by stating the server stores the submission as pending and returns it. Annotations already indicate write operation (readOnlyHint=false), so the description provides marginal additional behavioral insight.

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 core action, no filler. Every sentence is essential.

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

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

Given the tool has 8 parameters and no output schema, the description lacks details on return values, error handling, or formatting requirements, making it incomplete for a submission 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?

Schema description coverage is high (75%), so the description adds only minor value by noting 'dedup key' for URL. It does not significantly enhance understanding of parameters beyond the schema.

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

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

The description clearly states the tool submits a vacancy for moderation, with a specific verb and resource. However, it does not explicitly differentiate from sibling tools like 'jobs_add' or 'jobs_edit', so it's slightly below 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 description mentions required fields but provides no guidance on when to use this tool over alternatives, nor any when-not-to-use scenarios.

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?

With only readOnlyHint=false available, the description carries the behavioral load and does it well: delivery goes to the account's connected channels and "this conversation is not notified", invalid vocabulary values are silently dropped and surfaced in `ignored_params`, empty channels fall back to a defined default, and existing alerts are never mutated. These are non-obvious side effects an agent could not infer from annotations or schema.

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

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

Front-loaded with the definition before the workflow and the example, and nearly every sentence adds a distinct fact. Some clauses are dense and clause-stacked ("delivered to the person on the channels their account has connected..."), which costs a bit of readability without adding padding.

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

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

For a 6-param mutation tool with a nested object and no output schema, the description still covers return handling ("The answer's alert.id addresses the alert from then on"), validation feedback, defaults, and idempotency. An agent has everything needed to call it correctly on the first try.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: a worked JSON example of the nested `filters` object, the default-resolution rule for empty `channels`, the currency pairing for `salary_min`, and the derivation rule for `name`. Only `salary_max` and `query` are left entirely to the schema.

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

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

Opens with a specific verb and resource ("Create a job alert: a saved search over ANY of the job search's filters") and immediately defines the resource in terms of the sibling concept `search`. An agent can distinguish this from `update_subscription`, `list_subscriptions`, and `unsubscribe` without opening any schema.

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

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

Gives a concrete pre-call workflow ("Run the same search with `search` first so the person sees what they will get") and a validity constraint ("The search must narrow the catalogue"). It also implies create-only semantics ("reuses the one already selecting the same postings; nothing existing is changed"), though it never explicitly names `update_subscription` as the path for modifying an existing 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?

Goes well beyond the readOnlyHint annotation: it discloses ordering, the still-open-only filter, that matching runs every few minutes, that an alert only matches postings created after it and therefore starts empty, and the meaning of the `delivered` field. These are exactly the non-obvious behaviors an agent could otherwise misreport to a user.

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 core definition, then filtering, then the timing caveat, in three dense sentences with no filler. The 'matching runs every few minutes' clause earns its place by preventing a wrong interpretation of an empty result.

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 usefully explains the `delivered` field and the empty-until-matched behavior, which are the key unknowns. It stops short of describing the rest of the response shape or how `limit` interacts with paging, leaving a small gap for a four-parameter 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?

Schema coverage is 100% and documents id, days (default 7, max 30), limit, and since with RFC 3339 format. The description largely restates id/window semantics already present in the schema, and omits `limit` entirely; it adds little semantic depth beyond what the structured fields provide, 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 — listing postings matched by the person's job alerts — and immediately scopes it with 'the same matches their alerts are built from', which separates it from generic search or the alert-listing siblings. The ordering ('newest first') and filter ('still-open postings only') further pin down exactly what set is returned.

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?

Clear context for when this is the right tool (seeing what alerts surfaced) and how to narrow with id/since/days. It does not explicitly name alternatives such as `search` for general browsing or `list_subscriptions` for the alert definitions themselves, so the agent must infer the boundary from wording rather than an explicit 'use X instead'.

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 indicate idempotentHint=true; description reinforces this by stating it's a no-op if not saved. Adds value beyond 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?

Single sentence, front-loaded with action verb, no wasted words. Efficiently conveys purpose and 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 simple tool with one parameter and no output schema, the description covers purpose and idempotency. Lacks details on error handling (e.g., invalid slug), but overall adequate.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add any additional parameter information beyond what the schema already provides.

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?

Description clearly states the verb 'remove' and the resource 'job's bookmark', and distinguishes from the sibling tool 'save'. The no-op note adds clarity for edge case.

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?

Context is clear: use to unsave a job. The no-op note implicitly advises it's safe to call even if not saved. However, it lacks explicit when-not-to-use or alternatives beyond the sibling context.

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

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

Goes well past destructiveHint=true by saying exactly what is destroyed (the alert's delivery on those channels and their record of matches) and what survives (the saved search remains as a bookmarked search). That distinction between deleting delivery and deleting the search is the single most important behavioral fact here and is stated plainly.

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: action and scope first, consequence and retention second, alternative third. No filler and nothing important is 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 no output schema, the description plus annotations cover nearly everything: scope, destruction, retention, and the alternative. Minor gap: nothing about error behavior or whether repeating the call is idempotent when the alert is already gone.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds meaning: it frames id as identifying "one" alert and channel as the choice between all channels and a single one, reinforcing the omit-for-all semantics in prose. Enum values themselves are left to the schema, which is fine.

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?

Uses a specific verb and resource ("Stop one job alert by its id") and scopes it precisely ("on every channel or on the one named"). It is clearly distinguishable from subscribe, list_subscriptions and update_subscription, whose names appear in the sibling list.

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

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

Explicitly names the alternative and the condition that selects it: to hold an alert temporarily, use update_subscription instead of unsubscribing. That is a genuine when-not-to-use directive with a named sibling, not an implied one.

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 (readOnlyHint=false, idempotentHint=true), the description discloses rich behavioral details: empty filters clear facet filters, salary 0 clears a bound, website-only filters are kept, removed channels delete their match records, and unknown values are dropped and named in ignored_params. It also clarifies that digest timing is account-wide and unchanged, which an agent could not infer otherwise.

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 front-loaded with the core action and then layers parameter semantics logically. It is dense but every sentence carries useful information; the example earns its place. It is slightly long, but appropriate for the tool's complexity.

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

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

Given a complex mutation tool with nested filters and no output schema, the description covers clearing behavior, error handling via ignored_params, channel side effects, and account-wide constraints. Nothing an agent needs to call it correctly appears 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 would be 3, but the description adds substantial meaning beyond the schema: it explains replacement versus clearing semantics, distinguishes 'full set' channel behavior, and provides a concrete JSON example for a complex filter payload. This materially improves correct invocation.

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 ('Change one of the person's job alerts by its id') and references list_subscriptions for reading the current state. It distinguishes this from subscribe and unsubscribe implicitly, though it does not explicitly differentiate from subscription_updates, leaving a minor ambiguity among siblings.

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

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

It explicitly tells the agent to read the current search from list_subscriptions and pass only what changes, and it names a concrete alternative ('prefer it to unsubscribe for holding an alert'). The optional-field guidance and replacement semantics make when-to-use and how-to-invoke unambiguous.

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

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

Annotations already declare readOnlyHint=true, so the description's role is to add context. It adds value by specifying it returns user info and verifies the API key, with no contradictions.

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 purpose, no wasted words. Every sentence earns its place.

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

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

For a simple tool with no parameters and no output schema, the description is complete: it states functionality and usage context.

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 0 parameters, so baseline is 4. No parameter information needed in 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?

The description clearly states the verb 'return' and resource 'authenticated freehire user', and explicitly calls out it verifies the API key. It distinguishes itself from sibling tools by focusing on auth confirmation.

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

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

The description explicitly says 'Call this to confirm auth before other tools', providing clear usage context. While it doesn't mention when not to use it, the simplicity of the tool makes this sufficient.

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