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

With no annotations, the description carries the full burden. It does disclose non-obvious behavior about how the variant argument resolves ('saved for this job', 'auto' picks automatically, empty keeps the current choice), which is real value. However, it says nothing about side effects (where the PDF is written, whether it overwrites a prior build), permissions, or repeat-call behavior.

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

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

Two sentences, purpose front-loaded, with the parameter explanation compactly parenthesized. The parenthetical is dense but every clause adds information; 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?

No output schema and no annotations, so the description should be more self-sufficient than it is. It covers what is produced and how variant resolves, but omits the job_id source, the output destination, and any side effects, leaving an agent to guess at invocation 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 description coverage is 0%, so the description must compensate. It compensates well for variant, effectively enumerating its accepted values despite no enum in the schema. The required job_id parameter gets no explanation at all (format, source, or validity), so half the parameters remain undocumented.

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

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

States a specific verb (build) and a concrete artifact (tailored PDF resume) tied to a job, which clearly separates it from siblings like cover_letter_prepare or find_jobs. It stops short of naming an alternative tool or stating the full workflow context, but the action and resource are unambiguous.

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

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

There is no explicit when-to-use guidance: nothing says this is the step after selecting a job, that job_id must come from find_jobs/job_details, or that a prepare/submit flow does not apply here. The variant note implies the tool is called on an already-chosen job, but that is inference, not stated 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?

With no annotations, the description carries the full burden. It does disclose the non-obvious return behavior (a prompt, not letter content) and the required follow-up call, plus that language defaults come from coverletter/style.yaml. It says nothing about permissions, error cases, idempotency, or job_id validity, so the behavioral picture is only partially covered.

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?

Dense and front-loaded: the action comes first, then the language/default caveat, then the workflow instruction. No filler sentences, though the telegraphic phrasing around 'returns the prompt' reads slightly clipped.

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 prompt-generation tool with no output schema, the description supplies what an agent needs: the input semantics, the fact that output is a prompt to be obeyed, and the next call. Only failure/permission behavior is absent, which is a minor gap for this tool class.

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 neither property has a description, but the description supplies the real semantics for 'language' ('en' or 'no', default sourced from coverletter/style.yaml) which the schema lacks entirely. 'job_id' is left at name-only inference, so compensation is partial rather than complete.

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

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

States a specific verb+resource ('Start a tailored cover letter for a job') and clarifies the surprising mechanic that the tool returns a prompt rather than a letter. It also names the follow-up sibling (cover_letter_submit), so an agent can place it in the workflow, though it never explicitly contrasts itself with that sibling's own purpose.

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 operational context: call this first, write only the letter body from the returned prompt, then call cover_letter_submit. There are no explicit when-not conditions or scope exclusions, but the sequencing guidance is unambiguous for this tool's 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?

With no annotations, the description carries the full burden, and it does disclose a real side effect (creates PDF + plain text in the output folder) plus the gate that triggers it (passing checks AND accept_if_ok). It does not say what happens on failure, whether existing output files are overwritten, or what permissions/paths are required, which are significant gaps for a write-capable tool.

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

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

Two dense sentences, front-loaded with the validation purpose and with the consequential write behavior placed second where it matters. The parenthetical check list is long but each item earns its place by defining what 'passes' means.

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 no annotations, so the description should cover results too. It implies a pass/fail diagnostic but never says what the check returns on failure (error list? reasons?), nor what the output files are named or where exactly they land, leaving the agent unable to predict the response.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It usefully clarifies accept_if_ok's role (write only happens when checks pass and this flag is set) and body is described in passing as the letter to check, but job_id is never explained and no formats or constraints are given for any 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 gives a specific verb+resource ('Check a cover letter body') and enumerates the checks performed, plus the secondary action (making the PDF and plain text files). It is clearly distinguishable from a generic submit tool, but it never names or contrasts with the sibling cover_letter_prepare, so sibling differentiation 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?

Usage is implied rather than stated: the tool is meant to run on a drafted body, and 'If it passes and accept_if_ok' explains the conditional write path. There is no explicit when-to-use/when-not or pointer to cover_letter_prepare for the drafting step, so the agent must infer the workflow position.

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?

No annotations are provided, so the description carries the full burden. It discloses that problems include fix hints, but says nothing about whether the check is read-only, what permissions are needed, or how results are structured beyond the hint.

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 avoids waste. It is efficient, though the second clause is somewhat vague and could be more specific about output.

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

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

For a tool with no annotations, no output schema, and an undocumented parameter, the description is too sparse. It omits when to use the tool, what the parameter does, and any behavioral details beyond the existence of fix hints.

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% and the description does not mention the sole parameter 'check_sites' at all. With no explanation of what the boolean controls, the agent cannot infer its effect from the description.

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

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

States a specific verb ('Check') and resource ('installation and settings'), distinguishing it from the job/resume/config sibling tools. The added note that problems come with fix hints clarifies the diagnostic nature, though it does not explicitly differentiate from all 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?

Provides no guidance on when to use this tool versus alternatives. The mention of fix hints implies troubleshooting, but there is no explicit trigger condition, prerequisite, or alternative tool named.

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 no annotations, the description carries the full behavioral burden, yet it only hints that a search may still be running. It never states whether the call blocks, what it returns (new results vs. status), whether it writes data to the site, or rate-limit/auth constraints.

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 tightly-worded sentence with the primary action front-loaded. It wastes no words but is under-specified rather than genuinely concise.

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 two-parameter search tool with no annotations, no output schema, and undocumented parameters needs more than one parenthetical sentence to be callable 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?

Both parameters have 0% schema description coverage, so the description must compensate and does not: 'source' is never mentioned, and only the phrase 'check on a search already running' loosely gestures at the polling semantics of wait_seconds.

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

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

States a specific verb and resource ('Search the job sites'), so an agent can tell it initiates a job search. It doesn't differentiate itself from siblings like list_jobs or job_details, which is where it falls short of a 5.

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

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

The parenthetical '(or check on a search already running)' implies two usage modes — trigger a new search or poll an in-flight one — but names no alternatives or selection criteria against siblings such as list_jobs or job_details.

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 no annotations, the description carries the full behavioral burden. It usefully discloses that the call returns 'the prompt to follow' rather than completing an import, but says nothing about whether it writes files, what permissions are needed, or whether it is safe to re-run.

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 the action first and the input clarification parenthetical immediately after. No wasted 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?

For a one-parameter tool with no output schema, the essentials are covered, but as the opening step of a prepare/submit pair the description omits the follow-up step and any indication of what the returned prompt expects. An agent can call it, but not confidently place it in the workflow.

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

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

Schema coverage is 0% and the parameter name 'docx_path' is misleading, so the description earns real credit by stating it is the path to either a .docx or PDF file. It still omits path format (absolute/relative) and validation behavior.

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 ('Start a resume import from a Word (.docx) or PDF file') and clarifies the accepted input formats. It does not explicitly name the sibling it hands off to (import_resume_submit_tex), so sibling differentiation is only implied by the prepare/submit naming.

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 'Start' implies this is the first step of a flow, but the description never says when to use it versus import_resume_submit_tex or build_resume, nor what happens next. Usage must be inferred from the two-step naming convention.

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?

No annotations are provided, so the description carries the full behavioral burden, and it undersells the operation: 'Check' reads as a read-only comparison, yet the tool is named submit_tex and exposes an accept_if_ok flag that implies the check can commit or accept the imported resume. Nothing is said about side effects, what a mismatch does, or reversibility.

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. It is appropriately short, though the brevity is achieved partly by omitting needed information rather than by tight writing.

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 annotations, no output schema, 0% schema coverage, and an undocumented side-effecting flag, the description leaves an agent unable to call this correctly or predict its effects. It should at minimum explain what a successful check returns and what accept_if_ok does.

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% for both parameters. The description loosely implies the 'tex' input is the LaTeX file under test, but it never explains the required tex string's format or the accept_if_ok flag at all, which is the one parameter with real behavioral consequence.

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 action (check/compare) on a specific resource: the LaTeX version of an imported resume against the source Word/PDF. This places it in the import_resume_* workflow and separates it from siblings like build_resume or import_resume_prepare, though it never names a sibling explicitly and the name's 'submit' verb is not reconciled with the description's 'check'.

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

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

No when-to-use guidance, no stated prerequisites (presumably a prior import_resume_prepare call), and no indication of what to do if the check fails. The agent must infer the whole position of this step in the workflow from the name alone.

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?

No annotations are provided, so the description carries the full behavioral burden and does not meet it. It never states that this is a read-only operation, what happens with an invalid or unknown job_id, or whether any authentication/configuration is required. It partly discloses returned content ('description and keyword match') but nothing about side effects or failure modes.

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 compact sentence with no filler, and the scope ('one job') is front-loaded before the content hint. It is efficiently sized, though brevity here edges into under-specification rather than crispness.

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 lookup with no annotations and no output schema, the description minimally suffices: it says what the tool returns in broad terms. But with no output schema to fall back on, it should have enumerated the returned fields more concretely and explained the input identifier, so gaps remain.

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% and the single parameter (job_id, string) has no description. The tool description mentions 'one job' but never explains the identifier's format or where the agent should obtain it (presumably from find_jobs/list_jobs), so it does not compensate for the coverage gap.

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

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

The phrase 'Everything about one job' identifies the resource and its scope (a single job), implicitly distinguishing it from collection tools like find_jobs and list_jobs. However, it uses a vague catch-all ('everything') instead of a specific verb such as 'retrieve' or 'get', and it never names a 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?

There is no statement of when to call this tool versus find_jobs, list_jobs, or mark_job, and no prerequisites (e.g. that a job_id must first come from find_jobs). The only usage signal is implicit: the singular resource suggests lookup after a search, but nothing in the text says so.

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 no annotations, the description carries the full behavioral burden, but it only discloses the default ordering ('best match first'). It says nothing about pagination, whether hidden jobs are excluded by default, required auth, or what fields come back — notable gaps for a 6-parameter 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?

A single front-loaded sentence with zero filler is structurally clean. However, the brevity comes at the cost of under-specification rather than efficiency, so it is only adequate.

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

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

For a 6-parameter tool with no annotations and no output schema, the description gives an agent almost nothing beyond the ordering default. Missing are the meanings of the filter/sort parameters, pagination behavior, and the distinction from find_jobs.

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% across 6 parameters, so the description must compensate and largely fails. 'Best match first by default' weakly hints at the sort parameter's default, but search, status, min_match, limit, and show_hidden are left entirely undefined in both the schema and the description.

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

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

States a specific verb ('List') and resource ('saved jobs'), plus a scope hint that saved jobs are the domain. It does not differentiate from the sibling find_jobs, so an agent cannot tell from the description alone whether listing and finding are the same operation.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as find_jobs or job_details. The only implicit signal is the verb 'List' itself, which is the bare minimum.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Set status' implies a mutation, but it never states whether the change is idempotent, whether it can overwrite an existing status, what permissions are needed, or what happens on an invalid job_id — all material for a write 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?

A single terse line with no filler, and the enumerable values are placed immediately after the verb. It is efficient, though it borders on under-specification rather than deliberate 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 two-parameter mutation tool with no annotations, no output schema, and no schema descriptions, the definition leaves too much unspecified: the effect of the operation, idempotency, and failure behavior are all 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 0%, so the description must compensate. It does add real value by enumerating the accepted status values, which the schema does not encode as an enum. However, job_id is left entirely unexplained, so coverage is only partial.

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 (Set) and the resource being changed (a job's status), and the enumerated values make the intent unambiguous. It does not, however, distinguish itself from siblings like find_jobs or job_details beyond the implicit fact that it mutates rather than reads.

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 statement of when to use this tool versus the sibling tools, no preconditions, and no exclusions. The only guidance is the list of accepted status values, which is parameter information rather than usage routing.

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

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

With no annotations, the description carries the full behavioral burden and does reasonably well: it discloses a background server start, a browser-launch side effect, conditional execution ('if needed'), and the return value. It omits failure modes (port conflicts, browser launch failure) and whether the server persists, which keeps it 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, action first, return value last. Every clause earns its place 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 zero-parameter tool with no output schema, the description covers the trigger, the side effects, and the return format ('its address'), which is enough to call it correctly. Minor gaps around lifecycle and error behavior keep it just under 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 takes zero parameters and the schema is fully described, so there is no parameter nuance the description could add. Baseline 4 applies for a no-argument tool.

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 pair (start the dashboard, open it in the browser) plus the returned artifact ('its address'). No sibling tool overlaps with dashboard launching, so there is no ambiguity to 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?

The phrase '(if needed)' implies the call is safe to make when a dashboard may already be running, which is light usage context. There is no explicit when-to-use/when-not-to-use guidance, but with no sibling alternative for this capability there is little to disambiguate.

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 no annotations, the description carries the full burden. It usefully discloses two behaviors beyond the schema: partial-update semantics (only passed fields change) and that the prior file is preserved as config.yaml.bak. However, it omits permissions required, whether relative or absolute path resolution, and whether filters affect already-recorded jobs.

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 padding, and the core action and file target are front-loaded. Every clause carries information, including the backup behavior in the second 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?

For an 8-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, this is too thin. Key details an agent needs — value formats, matching semantics for include/exclude lists, units for max_age_days, and the effect of changes — are absent from both the description and the schema.

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

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

Schema description coverage is 0% across 8 parameters, so the description must compensate and does not: it never explains job_types, languages, locations, max_age_days, or the include/exclude list semantics. Nothing is added beyond the self-descriptive parameter names, and the numeric max_age_days unit and string-match rules are left undefined.

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

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

The description names a specific verb and resource: 'Change the job filters in config.yaml'. It is unambiguous about what is being modified, though it does not differentiate itself from siblings (which are mostly job/resume tools) or note relationships to diagnostic tools like doctor.

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 guidance on when to use this tool versus alternatives, no prerequisites, and no mention of when not to use it. The parenthetical '(only the fields you pass)' describes merge behavior rather than usage context, so an agent gets no routing help from this sentence.

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