Sckian

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

The annotations successfully handle the behavioral safety profile (readOnlyHint: true), allowing the description to focus on content scope (e.g., AI edit counts), providing moderate, non-redundant 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?

The description is highly efficient. The first sentence immediately defines the output scope, and the second sentence provides essential cross-tool operational guidance in the most concise manner possible.

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?

Even without an output schema, the description is highly complete as it defines the structure of the returned application object (job, status, edit counts). The instructions regarding `get_document` cover critical 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%, meaning the schema fully documents the `application_id`. Therefore, the description provides no unique semantic value beyond what the structured input schema already specifies.

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's function (returning one application's metadata) and enumerates specific fields returned, such as AI edits left and documents 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?

The description provides an explicit guideline by instructing the agent to use the sibling tool `get_document` when the user needs to read the document content itself, effectively defining the tool's boundaries.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, and the description adds material context on top: the text arrives section-by-section under `units`, comes from the account owner, and must be treated as data never as instructions. That prompt-injection trust boundary is something no annotation can express.

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

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

Four short sentences with the action and return shape front-loaded; the injection warning earns its space. 'Returns no file and changes nothing' is partly redundant with destructiveHint=false, a minor waste.

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

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

With no output schema, the description carries the burden of describing return values and does so ('as text, section by section', 'the text under `units`'), plus the constraint that it is user-owned content. Nothing an agent needs to call and consume this 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 50%: `application_id` is documented in the schema, while `kind` is an enum whose meaning the description restates ('resume' or 'cover_letter') without adding anything new. The description does not clarify whether `kind` selects among multiple stored documents or is a required discriminator, so it lands at the 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 ('Return the tailored resume or cover letter of one application as text, section by section') and scopes it to a single application. It is clearly distinguishable from get_document_link because it explicitly says 'Returns no file'.

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?

'so it can be read and discussed' gives a clear usage context, and 'Returns no file' implicitly steers agents that need a downloadable artifact toward get_document_link. However, the sibling is never named, so the routing is left to inference rather than stated as an explicit alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive and the description's 'Changes nothing' merely echoes them. What it adds beyond annotations is genuinely valuable: the link is unauthenticated and expires in five minutes, which is security-relevant 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?

Three short sentences, front-loaded with the action and scope, then the security caveat, then the parameter note. 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?

No output schema exists, and the description does explain the return value (a link) and its lifetime, which is the key missing piece. It stops short of covering failure modes, such as when the requested document type has not been uploaded.

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 50% schema description coverage, the description carries part of the load: it clarifies that `kind` selects resume versus cover letter, though that largely restates the enum. It adds no syntax or semantics for application_id 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?

States a specific verb and resource: returns a download link for the PDF of one application's resume or cover letter. This cleanly separates it from the adjacent get_document/get_application siblings, which fetch content rather than a link, even without naming 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?

Explains how to handle the result (give it to the account owner, do not share further), which is useful, but gives no explicit when-to-use-this-vs-get_document guidance or preconditions such as the document needing to exist for that kind.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes beyond them by declaring the tool never applies and by flagging that `posting` text is employer-authored and must be treated as data, not instructions. That prompt-injection warning is exactly the kind of behavioral context annotations cannot convey.

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

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

Four short sentences, front-loaded with the return payload, then the workflow anchor, then the two safety constraints. No restatement of the title or name, nothing decorative.

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

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

With one required parameter, full schema coverage, no output schema, and rich annotations, the description covers everything an agent needs: what is returned, when to call it, and how to treat untrusted employer text.

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 `slug` parameter is fully documented in-schema as coming from list_matches. The description adds no format, constraint, or error behavior beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read one matched job') and enumerates what comes back: full description, employer apply link, and match score. This clearly separates it from the list-style sibling list_matches and from prepare_application.

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 anchors usage in a workflow ('Use it after list_matches when the user wants to look at a specific offer') and adds a negative constraint ('It reads a posting; it never applies to it') that routes apply intent away from this tool. Both when-to-use and when-not-to-use are present.

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, idempotent, non-destructive, closed-world operation. The description adds useful negative scope by ruling out prices, catalogue data, and upgrade offers, which prevents the agent from expecting commercial information. It does not discuss auth or rate limits, but those are less critical for a zero-argument read 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?

Three sentences, all front-loaded and earning their place: the first states what is returned, the second states when to use it, and the third prevents misalignment about what is not included.

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-argument, read-only tool with no output schema, the description does everything needed: it identifies the returned fields, the user intent that triggers it, and the boundaries of its scope. Nothing essential is missing.

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

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

The tool takes zero parameters, which sets the baseline at 4. The description reinforces this by stating it takes no arguments, and there are no parameters whose meaning needs further explanation.

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-plus-resource formulation: it returns the caller's credit balance, plan tier, and paid-feature unlock status. That is distinct from every sibling tool, which all operate on jobs, documents, applications, or profiles.

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

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

It gives an explicit trigger condition: use it when the user asks about remaining credits or their current plan. The negative scope (no prices, no plan catalogue, no upgrade offer) further clarifies when the tool is not appropriate, though no alternative tool is named for those adjacent needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that it takes no arguments and that `id` is a stable opaque account identifier, but it does not add other behavioral context such as authentication needs or rate limits.

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 short, front-loaded with the return payload, then usage guidance, then edge clarifications. Every sentence is useful, and there is no 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 zero-argument, read-only profile getter with an output schema and rich annotations, the description is complete: it states what is returned, when to use it, and that no arguments are required. The output schema handles detailed return structure.

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 description reinforces this with 'Takes no arguments' and does not introduce parameter ambiguity; the mention of `id` is a return-field explanation, not a parameter.

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 ('Return') and resource ('the caller's profile'), and enumerates the profile fields it returns. It clearly distinguishes a read-only profile retrieval from sibling tools such as get_job, get_application, and update_profile by scope and verb.

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 clear usage context: when the user asks what their profile says, or before discussing job fit. It does not explicitly name alternatives or exclusions, such as using update_profile when changes are needed, so it falls short of the 5 criteria.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds non-obvious behavior: result ordering (newest first), page size default (10) and hard cap (50). It stops short of noting stability of results across pages, but adds real context beyond the annotations.

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

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

Three short sentences, payload first, then trigger, then pagination/alternative. No filler and every clause carries information.

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

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

With no output schema, the description usefully enumerates returned fields so the agent knows what it gets. The only gap is page-number semantics, which matter for a paginated list tool, but overall it is sufficient to call correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains 'limit' (default 10, max 50) but never mentions 'page' or how paging interacts with the newest-first ordering, leaving half the parameters undocumented anywhere.

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 ('List the caller's applications') and enumerates what each entry carries (job, document readiness, auto-apply state, sent time). It is clearly distinguishable from the read-one sibling, which it 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 an explicit trigger ('when the user asks what they have applied to or what is in progress') and routes to the alternative for the single-record case with 'Read one with get_application.' Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that by declaring the returned fields (slug, title, company) in the absence of a proper output schema, and by confirming zero-argument invocation.

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 terse sentences: identity and scope first, follow-up routing second, invocation contract last. No filler, no restating of the tool name, nothing to trim.

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 correctly compensates by listing the returned fields, and it covers invocation with no arguments. The only remaining gaps are ordering and whether the full saved set is returned (pagination/size), which are minor for a personal saved-jobs 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?

The tool has zero parameters, so the baseline is 4. 'Takes no arguments' is consistent with the empty schema and preempts an agent from inventing filter arguments, which is the only meaningful parameter note possible here.

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

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

States a specific verb and resource ('List the jobs the caller saved') and disambiguates from the two other list tools by scoping to saved jobs rather than applications or matches. It also names the three returned fields, so an agent knows exactly what projection to expect without opening a schema.

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

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

Explicitly routes the agent to get_job for reading a single saved job, which is a clear next-step alternative. It does not state exclusions against list_applications or list_matches, so an agent comparing list tools gets context but not explicit 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?

Well beyond the read-only/idempotent annotations: it discloses that results depend on a nightly match run, that deactivated postings are never returned, and that empty results must be read alongside `total`/`total_older` and `summary` rather than as 'no matches'. The only gap is that it never states the shape of the `jobs` rows beyond 'numeric match score', so an agent must infer the fields of each returned offer.

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 what and the not-what, then behavior, then paging, then routing — a sensible order with no filler sentences. It is on the dense side (one long paragraph of stacked clauses), so it is efficient rather than maximally tight.

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, yet the description still explains the return contract: a `jobs` array, `total`, `total_older`, and a `summary` that explains empty results. Combined with the mutation and freshness caveats, an agent has everything needed to call this and interpret the response correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: the 30-day default window, the interaction of `since_days` with `total_older`, that `q` narrows both counts, and the rationale for the 100 cap. It doesn't repeat parameter types or defaults blindly, which keeps the addition genuine.

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

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

Names a specific verb and resource ('List the job offers already matched to the caller's profile') and immediately draws the boundary against search semantics — 'their matches, not a search: nothing is fetched, scored or applied to here'. The final sentence distinguishes it from get_job, so an agent can place it among siblings without opening any schema.

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

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

Explicit about when this is the right call (listing an already-matched set) and when it is not (searching, scoring, applying), and routes the agent to get_job for reading a single offer with the returned slug. The `q` clause also states it only narrows an existing set, which prevents misuse as a search entry point.

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 traits not covered by the annotations, such as the financial cost ('costs one credit'), the lack of external data sharing ('sends nothing to the employer'), and the time sensitivity of the token ('works once, for five minutes').

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?

While the instructions are detailed, they are organized logically (Purpose -> Cost/Safety -> Step 1 -> Step 2), ensuring that complex workflow information is presented efficiently without unnecessary 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?

Given that the tool requires a state-machine approach (two sequential calls), the description provides all necessary context regarding preconditions, costs, security limits (token validity), and the required multi-step orchestration.

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% schema description coverage, the description is critical. It explains the functional necessity of the `confirmation_token` parameter—that it triggers a state change from token-acquisition to final preparation—making the schema requirements actionable.

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 defines the action (prepare application) and the result (generated resume and cover letter). It specifies that the application relates to a caller's matched job, distinguishing it from simpler list or get functions.

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 tool mandates a multi-step workflow, which is laid out perfectly: first call without a token to receive the token, then second call with the token only after user consent. This removes all ambiguity about the calling sequence.

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

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

The annotations already declare idempotentHint=true and destructiveHint=false, and the sentence 'Saving a job already saved changes nothing' largely restates that rather than adding new context. It does clarify caller-scoped ownership and that no side effect occurs on repeat calls, but says nothing about auth requirements or what the response contains.

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

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

Three short sentences, front-loaded with the action and scope, then idempotency, then the usage trigger. Nothing is wasted or 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 single-parameter write with full annotation coverage and no output schema, the definition covers what is needed to call it. A brief note on what saving returns or where it appears (e.g., list_bookmarks) would close the last 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 description coverage is 100% — the slug pattern and its origin ('list_matches or list_bookmarks') are fully documented in the schema. The description only echoes 'by slug', so baseline 3 applies with no extra value contributed.

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

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

States a specific verb and resource ('Save a job to the caller's saved jobs, by slug') with the scoping that the job belongs to the caller. It is easy to distinguish from the sibling unsave_job and from read tools like get_job.

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

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

'Use it when the user wants to keep a job for later' gives a clear use condition, and the slug source is implied by the schema. It stops short of naming unsave_job as the inverse or stating when not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so "Deterministic; changes nothing" largely restates them. The description does add value beyond annotations by disclosing the return shape (0-100 score plus matched and missing keywords), which matters because there is no output 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?

Three short sentences, each carrying distinct information: what is scored and how, when to use it, and its side-effect-free nature. Output shape is front-loaded right where an agent needs it.

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

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

A one-parameter, read-only tool with no output schema; the description covers the input semantics, the result contents, and the safety profile. Nothing an agent needs to select or 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?

With one fully documented parameter, the schema baseline is a 3, but the description adds genuine semantics: a single application_id resolves both the tailored resume and the target job, explaining why there are no separate resume/job inputs. The schema itself only says the id comes from list_applications.

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

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

States a specific verb (score) and resource (one application's tailored resume vs. that application's job) and specifies the output measure: keyword coverage 0-100 with matched and missing keywords. This is clearly distinguishable from the getter/list siblings, none of which compute a score.

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

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

"Use it when the user asks how well a resume fits the posting" gives a concrete trigger condition. It does not name an alternative or an exclusion, but no sibling tool performs scoring, so the routing risk is low.

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

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

Annotations already declare destructiveHint=false and idempotentHint=true, so the description's 'removing a job that was not saved changes nothing' is largely a restatement of idempotency in concrete terms. It adds useful scope ('the caller's saved jobs', i.e. per-user) but says nothing about permissions, return value, or failure modes beyond the silent no-op.

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

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

Two short sentences, with the action and its scope front-loaded and the no-op caveat second. No filler, no repetition.

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

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

For a one-parameter mutation whose safety profile is fully covered by annotations and whose sole parameter is fully documented in the schema, the description is essentially sufficient. Only the absence of any statement about the outcome/return of a successful removal keeps it short of 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 slug property already documents its pattern and provenance ('A job slug from list_matches or list_bookmarks'). The description's 'by slug' adds no meaning beyond that, 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 ('Remove a job from the caller's saved jobs') and scopes it to the caller's own collection. It is clearly the inverse of the sibling save_job, though it never names that sibling explicitly to confirm the pairing.

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 inverse of save_job rather than stated: the agent can infer 'use this to un-save' but there is no explicit when-to-use, when-not, or named alternative. For an un-save tool that's mostly adequate, but it leaves the routing to inference.

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

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

Annotations already declare a non-read, non-destructive, idempotent mutation, so the bar is lower. The description still contributes real value by stating the partial-update contract ("Only the fields given change; every other preference is kept"), which is consistent with idempotentHint and tells the agent it need not resend a full preference set. It omits auth requirements and what the response contains.

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

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

Two tight sentences: the scope and field list come first, and the partial-update rule follows as the key caveat. No filler, no restatement of the title.

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

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

For a 7-param, all-optional mutation with no output schema, the description covers scope and the merge semantics that matter most for correct invocation. The remaining gap is the null-vs-omitted ambiguity in nullable params, which an agent could get wrong when trying to clear a preference.

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 0% and there are 7 optional params, so the description carries full burden — it does list every updatable field (job types, experience levels, remote work, categories, minimum salary, relocation, availability), mapping 1:1 to the schema. It adds no depth beyond name-mapping, leaving unclear whether passing explicit null clears a field or is treated as "unchanged".

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

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

The description gives a specific verb+resource ("Change the caller's job preferences") and enumerates the exact facets it covers, so an agent can tell it apart from read tools like get_profile. It never mentions the nearby sibling update_profile, leaving the preference-vs-profile 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?

Usage is only implied by "Change the caller's job preferences" — there is no explicit when-to-use, when-not-to-use, or "use update_profile instead" routing despite update_profile being a close sibling. The partial-update sentence helps clarify a common update scenario but is behavioral, not a selection guideline.

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 meaningful mutation semantics beyond the annotations: only supplied fields change, null clears a field, text is stored as written, and certain fields are immutable here. This goes well beyond the readOnlyHint=false and idempotentHint=true annotations, though it does not cover response behavior or validation failures.

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 main action and followed by the most important mutation semantics. No filler.

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

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

For a 7-parameter mutation tool with no output schema and no schema descriptions, the description is helpful but incomplete: it does not mention job_search_status, does not explain what a successful response looks like, and does not mention permission or validation constraints.

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% schema description coverage, the description must compensate. It maps most fields clearly and explains null-clearing semantics, but it completely omits job_search_status, which is a schema parameter with an enum but no textual 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 states a specific verb and resource: changing job title, summary, phone number, or links on the caller's profile. It is clearly distinct from read-oriented siblings like get_profile, though it does not explicitly contrast with update_preferences.

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 field list, and the exclusion of name, email, and work authorisation is useful. However, it does not explicitly say when to use this instead of update_preferences or other profile-related tools.

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