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

With no annotations, the description carries the full load and does so richly: it declares the tool never raises for documented failures (all encoded in the return envelope), names every failure mode, explains the ambiguous_custom_title refusal-to-guess behavior, and justifies the anti-self-scoring guard. This is exactly the behavioral context 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?

Front-loaded with the core purpose and a numbered breakdown, and most sentences earn their place given the zero annotation and zero schema coverage. It is somewhat verbose with internal design references (D6/D7, module docstring) that add little for a calling agent.

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 an output schema exists, return values need not be explained, yet the description also covers the success/failure envelope shape. Combined with full parameter and behavioral coverage, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate and it does: all five parameters are documented, including non-obvious semantics like country being compared against work authorization and url/custom_title both being resolved to a job_id to keep the anti-self-scoring guard armed.

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?

It states a specific composite action (gather the general resume + scoring guide) and, crucially, disambiguates the name by declaring the actual scoring is NOT done here — the caller scores afterward. An agent can distinguish it from save_job_analysis or get_job purely from the text.

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

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

It clearly frames this as the first step and tells the caller what to do next ('after calling it, score the candidate's resume... apply the scoring_guide's recommendation_rules'). It also documents the precondition chain (resume must exist, work authorization must be declared). It does not explicitly name sibling tools or state when to prefer them, so it falls short of 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?

No annotations are provided, so the description carries the full burden. It discloses permanence (no undo, no confirmation flag), cascading effects (job_descriptions deleted, resume_versions unlinked with job_id set to NULL), the append-only trigger nuance, that it never raises, and the exact return structure with error codes. This is exceptionally transparent.

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 long but every sentence serves a purpose. It is front-loaded with the core action, then usage, then behavioral details, then parameters and return. Bulleted lists and clear section breaks make it scannable. The length is justified by the complexity of the delete operation and its cascading effects.

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 destructive nature, the description covers everything an agent needs: purpose, when to use, what gets deleted vs. unlinked, no-undo warning, the receipt as a safety mechanism, and all possible error returns. It also distinguishes from siblings and the `withdrawn` status, making it complete for safe 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 description coverage is 0%, so the description must compensate. It explains both parameters: id is 'preferred — always resolvable, unlike url' and url is 'Alternate lookup key when id is not known.' It also explains why custom_title is not a valid parameter, adding crucial semantic context beyond the bare 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 states a specific verb and resource ('Permanently delete a stored job record, by id or url') and explicitly differentiates itself from the `withdrawn` status and from get_job, which accepts custom_title. This makes the purpose unambiguous and distinguishes it from 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 clearly defines when to use the tool ('For a record that should never have existed: a mistyped entry, a posting that turned out to be a duplicate, test data'), explicitly contrasts with the `withdrawn` status, and explains why custom_title is deliberately excluded. It also notes that it is not the same as get_job, giving the agent clear routing 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 provided, the description fully carries the behavioral burden. It discloses that the tool NEVER raises, specifies exact outcomes for 0/1/many matches, explains the ambiguous error behavior, and notes that has_description is always present. This is exemplary transparency.

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 long but front-loaded with the core purpose, and each subsequent paragraph earns its place by explaining non-obvious behavior or hazards. There is no filler or redundant restatement of the schema.

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 moderate complexity and the absence of annotations, the description is complete: it covers lookup keys, matching semantics, error values, default behavior, return contents, and integration with sibling tools. The output schema can supply the remaining structural field details.

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%, but the description compensates thoroughly. It explains the meaning and uniqueness of each lookup key, the 'exactly one' constraint, the multi-match risk of custom_title, and the default behavior of include_description. This goes far beyond the bare 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 first sentence states a specific verb, resource, and scope: 'Retrieve a single job record by id, url, or custom_title.' This clearly distinguishes it from list_jobs and other siblings and immediately establishes the tool's lookup keys.

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 positions the tool as the 'REQUIRED read path for jd_text,' explains when id versus custom_title is appropriate, and contrasts with list_jobs for dumping records. It also names get_resume_version as the source for full resume text, giving alternatives and conditions.

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 burden and does disclose meaningful behavior: it 'NEVER raises' and enumerates failure modes (error="not_found" or "corrupt"). It omits auth/permission requirements and any rate-limit or store-scope caveats, so it is strong but not exhaustive.

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 in the first sentence, followed by terse Args/Returns blocks; every line adds information and there is no filler.

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

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

An output schema exists, so the Returns block is supplementary rather than required, and its error enumeration plus the never-raises guarantee give the agent everything needed to call and interpret results for a one-parameter lookup.

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, and it does: it defines id as either an exact version id or the magic literal "latest" for the most recently created version in the store. That is precisely the semantic an agent cannot infer from a bare string 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?

States a specific verb (Retrieve) and resource (a single resume version) with clear scope, and the word 'single' implicitly distinguishes it from the sibling list_resume_versions. An agent can identify the operation without opening the schema.

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

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

It explains the two modes of use (exact id vs the literal "latest") which helps an agent pick the right argument, but never states when to prefer this over list_resume_versions or get_job, nor any prerequisites for calling 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?

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses that the tool NEVER raises, validates arguments before building SQL, communicates validation failures through error_message, preserves pipeline order, and handles edge cases like None scores and ASCII-only case folding.

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 well-organized: a one-line summary, pipeline/validation context, detailed Args, and Returns. Some internal markers like 'SC-1' and 'D9' add minor noise, but every substantive sentence contributes to correct invocation.

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 six optional parameters, zero annotations, and no schema-level descriptions, this description is complete enough for correct use. It explains filtering, sorting, limiting, validation, failure behavior, and default ordering; the output schema covers the return shape.

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 document all parameters, and it does. Each of the six parameters gets meaningful detail: inclusive cutoffs, list-or-single status, None exclusions, case-insensitive substring matching, limit after sort, and sort_by valid values with defaults.

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 'Return stored job records with optional filtering, sorting, and limiting' clearly identifies an action and resource. The plural 'records' implies this is a listing tool rather than a single-record fetcher like get_job, but it does not explicitly name or differentiate from sibling 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?

There is no explicit guidance on when to use this tool versus alternatives such as get_job or other job-related tools. The description focuses on mechanics and semantics rather than usage context or exclusions, leaving the agent to infer when this is the right choice.

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

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

With no annotations, the description carries the full behavioral burden, and it does well: it declares ordering, the FILTER -> SORT -> LIMIT pipeline, that the tool NEVER raises, and that results contain summaries rather than resume text. It stops short of noting auth/permission requirements, but the error-free contract and payload shape are disclosed.

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

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

Front-loaded with the core behavior, then a compact pipeline note and Args/Returns blocks. The Args/Returns headings add a little structural overhead but every sentence carries 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?

For a two-parameter, read-only list tool with an output schema present, this covers ordering, filtering, pipeline order, failure contract, and payload granularity. The return-format sentence slightly duplicates the output schema, but no agent-critical detail 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 0%, so the description must compensate, and it does: it clarifies that job_id is an exact-match link filter and that limit is applied after sorting. This meaningfully exceeds the bare 'integer/string' types in the schema, though it doesn't state limit's default or bounds.

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 stored resume versions'), plus the default ordering (newest-first) and the optional-filter scope. An agent can immediately distinguish it from get_resume_version (single item) and save_resume_version (write) without opening any schema.

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

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

It explains the one filter condition ('job_id: when provided, only versions linked to this exact job id are returned'), which implies when the parameter is useful, but it never states when to prefer this tool over get_resume_version or how it relates to list_jobs. Usage is implied rather than directed.

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 at all, the description carries the full behavioral burden and does so thoroughly: 'This tool NEVER raises — all failures are encoded in the return envelope,' the omit-preserve rule, the 'title/company are NEVER used to match' safeguard against silent duplicates, the R1/SC-03 requirement that a new row resolve url or custom_title, and the unknown-id error='not_found' path. These are exactly the traits an agent cannot 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?

Well front-loaded (purpose, then resolution order, args, returns) and each sentence carries meaning. It loses a point for repetition of the omit-preserve rule across the body and per-arg list, and for unexplained internal codes (D10, R3, SC-04, R1, SC-03) that are noise to an agent with no key.

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 10 params, 0% schema coverage, and a complex multi-key upsert, the description covers resolution logic, per-param semantics, the new-row constraint, and failure encoding. An output schema exists, so the brief Returns note is sufficient; nothing needed to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must carry parameter meaning — and it documents all 10 args individually, distinguishing always-overwrite fields (title/company/country) from omit-preserve fields (url/custom_title/jd_text/score/recommendation/notes) and explaining id's create-vs-update role. This is a large value add over the bare schema types.

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 ('Persist an analyzed job record') plus the core mechanism ('Upserts by id then by url'), which cleanly separates it from read siblings like get_job/list_jobs and from analyze_job. An agent can identify the tool's role without opening the schema.

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

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

The three-step 'Resolution order' gives explicit conditions for when an id targets an existing row, when a url upserts, and when a brand new row is created, which is strong invocation guidance. However, it never names an alternative sibling (e.g. use get_job to read, analyze_job to compute), so the tool-vs-tool routing remains 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?

With no annotations, the description carries the full burden and does so thoroughly: it discloses the single-root tree invariant, foreign-key enforcement, verbatim raw storage, that it NEVER raises, and enumerates the exact failure codes (invalid_parent, parent_not_found, job_not_found, etc.). This is more behavioral detail than most schemas or 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 key guarantee is front-loaded and the Args/Returns structure is scannable. Slight bloat from internal jargon ('the FK is real now, D1/D8') that adds nothing for an agent deciding how to call it.

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

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

For a mutation tool with no annotations, the description covers constraints, prerequisites, success shape, and the full error vocabulary, so an agent has everything needed to invoke and interpret results. Although an output schema exists, restating the result fields is a harmless reinforcement rather than a 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 0%, so the description must compensate, and it documents all four parameters with meaning beyond the bare titles – content is stored verbatim, label is caller-supplied, parent_id's None-only-on-first-save rule, and job_id's FK requirement. The constraint semantics are essential and present.

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 ('Append a new resume version to the store') and immediately clarifies the append-only nature ('Never mutates or deletes'). This cleanly separates it from read siblings like get_resume_version and list_resume_versions and from save_job_analysis.

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

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

It states precise prerequisites and conditions: the first save's parent_id MUST be None, subsequent saves MUST reference an existing id, and job_id requires calling save_job_analysis first and passing its returned id. The append-only scope tells the agent when this tool is NOT the right one for changes.

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 provided, the description carries the full behavioral burden and does so thoroughly: it states transitions are deliberately unvalidated, the tool never raises, notes appends a dated line to status_notes and never touches the analysis field, and it documents all error modes such as invalid_status and not_found. The historical rationale for splitting status_notes from notes adds meaningful context beyond 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?

The description is front-loaded with the core action and then layers in behavioral caveats, parameter details, and return values in a logical order. The historical explanation for why notes and status_notes are separate is slightly longer than strictly necessary, but it earns its place by preventing a likely misuse. There is no repetitive 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?

For a mutation tool with no annotations, the description is complete: it covers what the tool does, all parameter semantics, exact failure modes, return payload fields, and the relationship to sibling tools like save_job_analysis. An agent has everything needed to decide when to call it and how to 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 description coverage is 0%, so the description must fully explain the parameters, and it does: status is enumerated with all valid values, id is the preferred lookup key, url is the fallback, and notes specifies its exact append format and behavior when omitted. This goes well beyond what the bare schema properties provide.

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

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

The description opens with a specific verb and resource: 'Set the application status of a stored job record, by id or url.' It also distinguishes itself from save_job_analysis by clarifying that editing analysis is a separate sibling tool's job. The seven allowed statuses are listed explicitly, leaving no ambiguity about what the tool operates on.

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 gives clear when-to-use guidance: use id over url because id is always resolvable, use this tool for status changes, and use save_job_analysis with an id to edit analysis fields. It also explains the note-append behavior versus the analysis field so the agent does not misuse notes. This is explicit routing, not merely 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?

With no annotations present the description carries the full burden and does so: it discloses the full-replace semantics, that it NEVER raises, the rejection path when all entries canonicalize to nothing, and all three error codes (invalid_input, corrupt, write_error). Canonicalization behavior and the 'first raw spelling wins' echo rule are also spelled out.

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 contract and structured with explicit Args/Returns sections, but the parenthetical requirement IDs (SC-26, SC-27) and internal module path (tools/_country.py) are implementer-facing noise that a calling agent does not need. Slightly long, but nearly every sentence carries behavioral weight.

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 tool with no annotations, the definition covers semantics, edge cases, failure modes, and return shape completely. Although an output schema exists, the description's brief return summary is a bonus rather than a redundancy, and nothing needed to invoke the tool 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 0% and the single required parameter is fully compensated: free-text country names as the user states them, empty list explicitly declares zero countries, non-country entries like '', ' ', '...' are dropped, and the rejection behavior when nothing remains. An agent knows exactly what to pass and what happens to edge-case input.

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 ('Declare the FULL set of countries the user may legally work in') with the scope constraint ('FULL set') front-loaded. No sibling tool overlaps this action, so an agent can route to it unambiguously.

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 that the call replaces the prior declaration rather than appending, that an empty list is a distinct valid declaration, and ties the distinction to how analyze_job interprets it (no_work_authorization only for 'never declared'). This is strong contextual guidance, though it does not frame when to call this versus any other sibling — reasonably so, since no sibling offers an alternative.

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