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

Goes well beyond the annotations: annotations only say readOnlyHint=false, idempotentHint=true, destructiveHint=false, while the description discloses the mechanism (sets archived_at), confirms reversibility, and enumerates exactly what is preserved (JSON, PDF, TEX, version history) and what changes (drops out of list_base_resumes' default view). No contradiction with annotations; mutation with idempotent=true is consistent with re-archiving being harmless.

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 purpose, then mechanism, then the undo path. Every sentence carries distinct information with no repetition of the title or annotations.

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

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

For a one-parameter, non-destructive mutation with no output schema, the description covers the essential facts an agent needs: what changes, what persists, effect on other tools, and how to reverse it. Nothing material about calling it correctly is missing.

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

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

Schema description coverage is 0% and the description never mentions the slug parameter, so it adds no meaning about identifier format or where to obtain it. With only one unambiguous parameter in a family where slug is the standard key, the gap is minor, but the description does no compensating work.

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

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

States a specific verb and resource ('Hide a base resume from pickers') and immediately disambiguates from a sibling action by clarifying it is not a delete. An agent can distinguish this from update_base_resume, edit_base_resume, or a delete-style operation without opening any schema.

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

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

Gives clear context for use (removing a base from pickers while preserving it) and names the exact reversal path, unarchive_base_resume. It stops short of stating when NOT to archive (e.g., to permanently remove a base, use something else), so it is clear but not fully exclusionary.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the bar is lower. The description adds the inline-base64 transport detail and the alternative's rationale, but says nothing about what happens on repeat attaches (relevant given idempotentHint=false), size limits, or permissions on the proposal.

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 core action and the routing alternative. The final sentence restates the schema enum verbatim, so it earns slightly less than a perfect score, but nothing is padded.

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 mutation tool with four required parameters, no output schema, and zero schema description coverage needs more than transport hints. Missing are the semantics of step/label/proposal_id, behavior on duplicate attaches, and any constraint on image size or format beyond 'base64', leaving real gaps for correct invocation.

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

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

Schema description coverage is 0% across 5 parameters, so the description must carry the load. It explains image_base64 (inline base64 rather than a path) and restates the kind enum, but says nothing about step, label, or proposal_id — the meaning of step (index? existing step reference?) and what label is used for are left entirely 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 and resource (attach an evidence image to a proposal) and immediately names the sibling it is not — attach_evidence_file — with the condition that separates them. An agent can pick between the two without opening either schema.

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

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

Explicitly routes the agent: use this tool when the image is supplied inline, use attach_evidence_file when the screenshot already exists as a file on this machine so bytes never pass through model context. No exclusions or prerequisites are given for the kind values or for when attaching evidence is appropriate, which keeps it short of a 5.

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

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

Adds substantial context beyond the write/non-idempotent annotations: file bytes are read and uploaded server-side so they never enter model context, path resolution rules (relative/~ vs absolute), container mount behavior, refusal of paths leaving the tree, and hard constraints (PNG/JPEG, 5 MB max). This is exactly the kind of behavioral disclosure annotations cannot carry.

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

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

Purpose and the key constraint are front-loaded, and each sentence carries real information. The embedded hard-coded example path (/Users/<user>/Projects/maestro-career-studio/...) is verbose filler that could be trimmed without loss.

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 5-param mutation with no output schema and 0% schema coverage, the description covers the file-handling dimension thoroughly but leaves the identity/placement params (proposal_id, step, label) and success behavior unexplained. Adequate but with clear gaps.

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

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

Schema coverage is 0%, so the description must compensate, and it does richly for file_path and the kind enum values. But proposal_id, step, and label — three of the four required params — are entirely undescribed in both schema and description, leaving half the call under-specified.

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: attaching evidence from an image file already on disk. Clear what it does, though it never explicitly contrasts itself with the sibling attach_evidence (the non-file variant), so an agent must infer the split from the name alone.

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

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

Gives concrete context for when this is used — a browser tool's saved screenshot reported by path — which sorts it from a generic evidence attach. However, it offers no explicit when-not or named alternative routing to attach_evidence.

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 give the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real state-machine context beyond them: it marks status 'abandoned', explains the intent (stops looking like unfinished work), and lists the exact 409 failure conditions (already tailored/superseded/abandoned). This is consistent with idempotentHint=false.

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

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

Front-loads the core action, then the scenario, then the status effect and error behavior. No redundant sentences; each line contributes distinct information.

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

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

For a single-parameter state-transition tool with no output schema, the description covers purpose, when to use, what state changes, and error conditions. 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?

With only one parameter and 0% schema description coverage, the description carries the burden and does so by explaining provenance: tailoring_session_id is the id returned by create_tailoring_session. It doesn't add format/syntax detail, but provenance is the meaningful gap an agent would otherwise lack.

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 (abandon/close) and resource (OPEN tailoring session) plus the key scope qualifier 'without tailoring it'. This cleanly separates it from tailor_session and create_tailoring_session, so an agent can distinguish it 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?

Explicitly describes the 'changed my mind' scenario where the user walks through gaps then decides to use the base resume as-is and does not run tailor_session. It names the alternative (tailor_session) and the condition that selects this tool, and even documents the 409 error when the session isn't open.

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), but the description adds real behavioral context by disclosing the diff taxonomy (absent→matched, skills-list-only→dual, decayed→recent) and the lazy behavior 'computes any missing phase row on demand'. That last clause hints at an on-demand computation/persistence step that annotations alone would not reveal.

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, front-loaded with the core comparison purpose and followed by the supporting detail. No filler; the second sentence about computing missing rows earns its place by adding behavior not present elsewhere.

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 describes the return shape (composite/per-layer deltas, per-skill diff) and the on-demand computation behavior. For a one-parameter read tool the only real gaps are the absent usage guidance and parameter documentation.

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 never mentions application_id, so it does not compensate for the gap. However, the single parameter is self-documenting by name with no format or syntax nuance to explain, so the omission is low-cost.

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 (compare) and resource (before/after match scores) and even enumerates the output components: composite and per-layer deltas plus a per-skill diff. It is clearly distinguishable from score_ats (which produces a single score) by the 'before/after' framing, though it never names the sibling explicitly.

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

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

The 'before/after' framing implies the scenario (comparing an application's match state across phases), but there is no explicit when-to-use statement and no routing versus score_ats or explore_ats_over_time. Usage is inferable from context rather than stated.

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

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

Annotations already disclose that this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds a real operational constraint (slug format and the reserved 'master' value) but says nothing about failure modes on duplicate slugs or what the returned object 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 short sentences, no filler, purpose stated first and the constraint second. Efficient, though extremely terse for a creation tool.

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

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

For a write tool with a nested free-form 'data' object, no output schema, and zero schema coverage, the description leaves too much unexplained — what shape 'data' takes and what a successful create returns are both unspecified.

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 three required parameters. The description only constrains 'slug' (lowercase alphanumeric/underscores, not 'master'), leaving 'display_name' and especially the nested 'data' object entirely undocumented in both schema and description.

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

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

States a specific verb+resource ('Create a new base resume') that is unambiguous. It does not differentiate itself from the sibling create_base_resume_from_kb, which an agent might reasonably confuse it with.

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 the alternative create_base_resume_from_kb. The agent must infer from the name alone which creation path to take.

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

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

Adds substantial behavior beyond the annotations: 422 semantics for unknown role_category, unmatched role_label mapping to 'other' with a slug scheme, slug minting on repeat calls (<slug>_2), draft vs approved point filtering, skills/contact always arriving in full from the KB profile, and summary suppression rules. This is consistent with idempotentHint=false and destructiveHint=false and discloses mutation side effects the annotations only imply.

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

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

Purpose and the required-argument rule are front-loaded, and nearly every sentence carries non-obvious information. It is dense and somewhat sprawling with mid-sentence line breaks, but there is little pure filler for a tool with this many edge cases.

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, so the description compensates by describing the return shape ({base, next}), the meaning of next as a hint, when it is null, and that the base is created regardless. For a 6-parameter, non-idempotent mutation tool it covers the failure modes, side effects, and output an agent needs.

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

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

With 0% schema description coverage, the description carries the full burden and does: entity_ids required + empty-list behavior, role_label vs role_category precedence and strict validation, display_name having no effect on the slug, include_summary gating the career summary, and the reviewed summary option. Every one of the 6 parameters is given meaning.

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

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

States a specific verb and resource ('Compose a new base resume from selected Career KB entities') and adds the distinguishing constraint 'LLM-free', separating it from siblings like create_base_resume and kb_sync_base. An agent can tell what this does 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?

Gives clear preconditions: entity_ids is REQUIRED, an empty list deliberately 422s, and a role_label or role_category must be supplied. It explains the approved-points gate (kb_ingest_resume drafts contribute nothing until kb_approve_points). It does not explicitly name when to choose this over create_base_resume or kb_sync_base, so no full when/when-not routing.

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

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

Annotations flag destructive/non-idempotent, but the description explains WHY: re-calling makes saved resolutions unreachable. It further discloses that the base score is deterministic and persisted as the 'before' score, and precisely what enrich does and does not change (no score/gap-set change, no LLM call by default, KB autos stamped even during an outage).

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

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

Front-loads purpose and the destructive supersede warning before the enrich detail. Sentences are dense and mostly earn their place, though the enrich/KB paragraph is verbose enough to risk burying the operational essentials.

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 nonetheless describes the response shape (the session, gaps_json.categories ordering, the `next` hint, base_anchors) and the constraint that gap actions are limited (add_keyword only into a skills category, else user_input/attach_project/skip). Complete enough for an agent to invoke and interpret results.

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 the burden. It fully explains the non-obvious `enrich` parameter (default, cost, effect on enrichment fields only), but job_id and base_resume are never described beyond their self-evident identifier roles. Strong compensation for the covered parameter, partial gap on the other two.

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 the gap-analysis tailoring workflow for a job + base resume.' This clearly distinguishes it from read-only siblings like list_tailoring_sessions, get_tailoring_session, and close_tailoring_session, and from the downstream tailor_session.

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 warns that calling again for the same job+base SUPERSEDES the open session, and names list_tailoring_sessions as the way to inspect existing sessions. It also lays out the intended downstream flow (gather answers, resolve_gaps, then tailor_session), so the agent knows where this sits in the 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?

Annotations only declare the safety profile (write, non-destructive, non-idempotent); the description goes far beyond: engine is immutable after creation, drafts are not usable until validation succeeds, LaTeX cannot validate on a backend without TeX, Typst rejects @-imports, unknown fonts silently substitute without error, templates that skip r.extra_sections hard-fail, and HTML entities are not decoded. These are exactly the non-obvious behaviors an agent must know before writing source.

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

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

Front-loaded with the core action and the engine branch, then progressively details Typst constraints, LaTeX format, and validation. Dense but each sentence carries operative information. It is long for a tool description and the Typst/LaTeX blocks could be slightly tightened, so it is not a model of concision, but little is 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 5-parameter, no-output-schema mutation tool, the description covers the full call surface plus the failure modes: what source must contain per engine, what validation does and reports (status/last_error), engine availability via list_templates, and post-creation immutability. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: engine default and the source-required-for-typst rule, the exact required format of source per engine (raw .typ with sys.inputs access vs. complete Jinja2 LaTeX document with ((* *)), ((( ))), ((# #)) blocks), validate's test-compile semantics, and id's slug charset [a-z0-9_-]. Only display_name is left undocumented, which is self-evident.

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 + lifecycle state: 'Create a DRAFT template.' Distinguishes itself from siblings by naming the read path (get_template), the enumeration tool (list_templates), and the mutation follow-up (update_template_draft implied), so an agent can place it in the template lifecycle without opening another schema.

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

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

Gives concrete conditional guidance: engine defaults to 'latex'; pass engine='typst' and then source becomes REQUIRED; omit source for the LaTeX canonical starter; validate=True test-compiles in the same call. It also names get_template('default') and get_template('typst-classic') as starting points. It does not explicitly route 'editing an existing draft' to update_template_draft, so it stops 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is partly covered. The description adds nothing beyond that: it does not say whether the copy is deep or shallow, whether source content is left untouched, or what happens if new_slug already exists (annotations mark idempotentHint=false, so a collision error is plausible but unstated).

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

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

A single short sentence with the verb and target front-loaded and no wasted words. It is concise, though the brevity comes partly from under-specification rather than disciplined editing.

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 three undocumented parameters, no output schema, and only a default-valued third argument, the description omits too much: no mention of the third parameter, no collision behavior, and no indication of what the new resume inherits. An agent could call it, but with avoidable guesswork.

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 the load, but it only gestures at two of the three parameters ('existing' slug and 'new slug'). The optional new_display_name is never mentioned, nor is uniqueness/format expected for new_slug or the default display name of the clone.

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 ('Clone') and resource ('base resume') plus the outcome ('into a new slug'), so an agent knows this is a copy operation. It does not, however, distinguish itself from close siblings like create_base_resume, create_base_resume_from_kb, or kb_sync_base, which could also produce a new resume.

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

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

There is no when-to-use guidance and no mention of the alternatives that produce a new base resume (create_base_resume, create_base_resume_from_kb, kb_sync_base). The agent must infer that this tool is for copying an existing resume rather than building one from knowledge-base data.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, but the description adds real operational context beyond them: prior edits are preserved incrementally, the base-resume fallback only fires when customized_json is absent, and pdf_path/tex_path are cleared because the old PDF is stale (with render_pdf as the recovery). It doesn't cover auth/permission requirements or how a partially-failing op batch is reported, keeping 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?

Front-loaded with the mode ('INCREMENTAL FIX') and then layers fallback, usage, alternative, op vocabulary, and field-name constraints in a logical order. Every sentence carries operational weight, though the op-vocabulary and key-name sections are dense enough that a couple of clauses could be tightened.

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, but the description compensates by documenting the response shape (`applied[].name` echoes each touched entry) and the side effect on pdf_path/tex_path plus the render_pdf recovery. Nothing critical for correct invocation is missing; only error/partial-failure semantics go unaddressed.

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 only 50% (application_id has no schema description), so the description must compensate, and it does: it pins exact key names ('kind' not op/type, 'index' not entry_index, 'value' not text), specifies 0-based indexing into the FULL array including enabled:false rows as shown by get_application, and points to edit_base_resume for the full op vocabulary. This maps directly onto the loosely-typed ops array and adds meaning the schema alone does not convey.

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 and a precise operation mode: 'apply typed edit ops on top of an existing application's CURRENT tailored resume (customized_json), preserving every prior edit.' It explicitly distinguishes itself from tailor_application (from-scratch) and update_base_resume (whole-resume replace), so an agent can disambiguate without opening schemas.

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

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

Gives explicit when-to-use ('refining or retrying a tailored resume after inspecting PDF previews — swap a bullet, tweak wording, fix one thing') and names the alternative with the condition that selects it: tailor_application recomputes off the BASE resume and discards tailored edits. Also covers the no-customized_json fallback case. Routing is fully specified.

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 annotations already declaring destructiveHint=true and idempotentHint=false, the description goes beyond them by disclosing error conditions ('Bad index/category/key → error'), the PDF re-render side effect, and the render_error/stale-PDF signal. It does not state whether a batch of ops applies atomically or partially, which is the remaining behavioral gap.

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

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

Front-loaded with purpose, the key sibling distinction, index semantics, and response semantics before the long op catalogue, and the bulleted JSON sketches keep it scannable. It is nevertheless a dense wall of near-schema duplication (the kind list reappears in the schema description), so some redundancy exists.

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 high-complexity batch-mutation tool with no output schema, it explains the `applied` echo and render_error return semantics adequately. It omits atomicity/partial-failure behavior and never defines the required `slug` parameter, so it is not fully closed.

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 description is the de facto documentation for the polymorphic `ops` array, spelling out the shape of all 16 op kinds, index base ('0-based into the FULL array incl. enabled:false, never PDF order'), and enum-like constraints for <sec>, section_key, and case-insensitive category. It adds far more meaning than the schema's 50% coverage provides.

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

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

States a specific verb and resource ('Apply typed edit ops to a base resume') and immediately contrasts itself with the sibling update_base_resume ('instead replaces the whole resume body (PUT)'). An agent can distinguish the two mutation tools without opening either schema.

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

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

Gives a clear when-to-use rule for the key ambiguity: 'replace_entry changes a field on one entry ... a whole-resume replace is the separate update_base_resume tool.' However it never explains when to reach for edit_base_resume at all versus versioning/tailoring alternatives, and it introduces expected_content_hash without saying when an agent should supply 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context — that results are weekly aggregates split by phase and role category — but says nothing about the time window, bucketing boundaries, or whether empty buckets appear.

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

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

Two short sentences, front-loaded with the metric and granularity, then the filters. No filler or 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 read-only aggregation tool with no output schema and undocumented parameters, the definition covers what is aggregated and how it is split, which is the core. It is still missing the time range covered by 'over time' and any expectation about result shape, which an agent would need to interpret the output.

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 three properties (level, role_category, employment_type) have no descriptions, so the description is the only source. It partially compensates by naming 'role/level/type' as the filter dimensions, but gives no accepted values, casing, or format, leaving the agent guessing at valid inputs.

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 metric (average match score), a granularity (weekly), and the two splits (phase base vs tailored, role category) — enough to distinguish it from most siblings like explore_role_mix_over_time. It does not, however, explicitly separate itself from adjacent ATS analytics tools such as explore_tailoring_lift or compare_ats.

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 only usage sentence is 'Optionally filtered by role/level/type,' which describes parameters rather than when to choose this tool over alternatives. There is no guidance on when the trend view is preferable to explore_tailoring_lift or compare_ats.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful field semantics — that display_name is the resume's own name and is null for a slug with no row, and that the slug is an internal identifier — but says nothing about the granularity of the distribution, ordering, or how scores are bucketed.

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

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

Two short sentences with no filler, front-loaded on what is distributed. The parenthetical about the deterministic engine and the display_name note both earn their place, though the sentence flow is slightly choppy.

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 and no parameters, the description must carry the whole burden, and it only partially does: it explains two output fields but not the shape of the result (per-resume rows vs. buckets, score ranges, ordering) an agent needs to interpret a 'distribution'.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description need not document any inputs, and the empty schema is consistent with that.

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 subject — per-base-resume match-score distribution across jobs — and clarifies the deterministic engine as the source of the scores. It reads clearly as an analytics/distribution tool, though it never explicitly differentiates itself from the other explore_* siblings (top_skills, role_mix_over_time, skill_heatmap).

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

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

There is no when-to-use guidance and no named alternative, despite a crowded explore_* family where an agent must choose among several distribution-style tools. Usage is only inferable from the name and the word 'distribution'.

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, closed-world), so the bar is lower. The description adds real behavioral context beyond them: ranking semantics, exclusion of mirror_wording hygiene gaps and why (full keyword credit means no score movement), and guidance that raw keys (dual_place, missing_skills, tier values) are internal with category_label as the user-facing wording.

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

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

The core definition is front-loaded in the first clause and the following sentences are dense with interpretation-relevant guidance rather than filler. It runs long, and the internal-identifier aside is somewhat discursive, but each part earns its place by preventing misreading of the 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?

With no output schema, the description must convey the return shape, and it does: each row carries category_label and ranking by job demand plus potential match-score gain. Filtering behavior is sketched but not specified in detail, which is the main remaining gap.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden. Its single line 'Optionally filtered by role/level/type; limit caps the number of skills returned' maps all four schema params to plain words, but supplies no value formats, allowed values, or defaults for level, role_category, employment_type, or limit.

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

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

States a specific resource and scope: skills recurring as gaps across saved JDs, measured on best-scoring base resume vs JD before tailoring, ranked by job count and potential match-score gain. It clearly disambiguates from a 'you lack this / learn-next' interpretation. It does not name sibling analytics tools (explore_top_skills, explore_skill_heatmap, resolve_gaps) by name, so sibling differentiation is partial.

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 what this output represents and explicitly redirects the learn-vs-move question to another surface ('the learn-vs-move distinction is the per-skill tier on build_areas ... get_job_search_brief carries build_areas'). That is a concrete when-to-use-something-else pointer, though it never states a positive trigger condition for calling this tool.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context. It contributes the output granularity (per week) and grouping dimension (role category), but says nothing about data scope, default time range, or cardinality of the result.

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 clause with zero filler — the grouping and the time bucket both land immediately. It is arguably too terse for the tool's analytical role, but no sentence 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?

With no parameters and no output schema, the description carries the burden of explaining the shape of the result, and it only partially does: it names two dimensions but not the time horizon, whether counts span all jobs or the user's jobs, or the form of the returned series. Adequate minimum but with clear gaps.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify on the input side.

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 computation and grouping: counts of jobs grouped by role category, bucketed per week. That distinguishes it from explore_ats_over_time and explore_tailoring_lift by subject matter, but the description never names those siblings or explicitly frames the tool as an analytics/exploration query, so an agent must infer the routing from the shared 'explore_' prefix.

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

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

There is no when-to-use guidance at all — no statement of what question this answers, no indication of the time window analyzed, and no mention of alternatives among the six other explore_* siblings. The noun-phrase style implies an exploratory query but leaves all selection logic 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered externally. The description contributes the metric definition (pct of jobs per skill x role), which is genuine context, but says nothing about granularity, aggregation scope, or default sizing.

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 short sentence with no filler, and the core metric is front-loaded. It is efficient, though arguably too terse given the undefined parameter.

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

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

There is no output schema, so the description must convey the shape of the result; it only implies a matrix without saying whether it returns rows, a grid, or serialized cells. Combined with the undocumented 'limit', it is not complete enough to invoke confidently.

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 'limit' is never mentioned in the description. With no explanation of what limit bounds (skills, roles, cells) or its default of null, the agent must guess its meaning entirely.

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 what is computed (skill demand as a percentage of jobs per skill x role), which is more than a restatement of the title. However, it never uses a verb like 'compute' or 'return', and it does not distinguish itself from the sibling analyze tool explore_top_skills, which also deals with skill demand.

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

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

There is no when-to-use guidance, no condition under which this heatmap is preferable to explore_top_skills, and no mention of prerequisites or data assumptions. The agent gets no routing help.

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 closed-world, so safety is covered. What the description adds is genuinely beyond that: the return shape is grouped per role category with an additional overall row. It still leaves the unit of 'lift' (raw points vs. percentage) and empty-result behavior unstated, so it is good but not complete.

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

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

Two tight sentences with the core definition front-loaded and the filter caveat last; no filler. The shorthand 'role/level/type' is slightly compressed relative to the schema's actual field names, which costs a little clarity but not economy.

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 and 0% schema description coverage, the description must carry the burden and does cover purpose, aggregation grouping, and the optional-filter behavior. It omits valid filter values, the scale/unit of the lift score, and how many rows to expect, which an agent needs to interpret or call this confidently.

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 three nullable string parameters. The description maps loosely onto them ('role/level/type' covering role_category, level, employment_type) and confirms they are optional filters, but gives no accepted values, matching semantics, or whether filters are exact or partial. It compensates only partially.

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 computed metric (tailoring lift on match score, base->tailored) and its aggregation unit (per role category plus an overall row), which distinguishes it from sibling explore_* tools like explore_fit_distribution or explore_ats_over_time. It does not explicitly name an alternative sibling, but the resource being measured is 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?

The only usage cue is that filters are optional. There is no statement of when to reach for this tool versus explore_fit_distribution, score_ats, compare_ats, or get_tailoring_session, nor any prerequisite or scope condition. The agent must infer intent from the metric 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description only adds the data source (stored JDs) and optional filtering; it says nothing about aggregation basis, ranking, or how many results come back.

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

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

One tight sentence with the scope front-loaded and no filler. It is efficient, though the brevity is part of why the parameter and return semantics are underspecified.

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 analytics tool with no output schema, an agent cannot tell what the response looks like (ranked list? counts? share percentages?) and gets no filtering vocabulary. Given 0% schema coverage and four undocumented parameters, the single sentence is not enough.

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 no parameter has a description or enum, so the description carries the full burden. It names role/level/type, loosely mapping to three of the four parameters, but leaves valid values unspecified and never mentions limit at all.

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

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

States a specific operation and resource: ranking the most in-demand skills across stored JDs. An agent can tell what it retrieves, though it never contrasts itself with the nearby explore_skill_heatmap or explore_gap_frequency, which cover adjacent analytics.

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?

"Across stored JDs, optionally filtered by role/level/type" implies the context of use and that all filters are optional, but there is no when-to-use guidance and no mention of when a sibling like explore_skill_heatmap would be the better pick.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds real behavioral detail beyond them: pagination semantics (page shorter than limit is the last), row size in characters, and the fact that raw_text and extracted_json are omitted. Return format is only partially covered (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?

Dense but front-loaded: purpose first, then pagination, then payload shape, then parameter formats. Every sentence carries information, though the parenthetical asides add some length without changing agent behavior.

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

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

For a 6-param read-only export with no output schema, the description supplies the pagination contract, row-size expectations, and omitted fields, which is what an agent needs to call it. The only shortfall is the undocumented level and role_category filters.

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 the load. It documents limit (default 10, max 50), offset, since (ISO YYYY-MM-DD), and skill (case-insensitive substring), which is most of the parameter surface. However, the level and role_category filters are left entirely unexplained, which is a real gap for a 6-param 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 (export jobs), the ordering and payload shape (newest first, extracted fields, nested skills), and the intent (open-ended analysis). It explicitly distinguishes itself from get_job, which returns raw_text and extracted_json for a single posting, so an agent can route 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?

Frames the use case (open-ended analysis, bulk export) and names get_job as the single-posting alternative. It stops short of explicit exclusions against sibling list_jobs, so the when-not-to-use case is inferred rather than stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral detail beyond them: the matching algorithm (ignores ?utm_*/?gh_src=/#apply, treats /apply and /application as the same posting), what counts as a non-match, and the meaning of found=False. That is exactly the extra context a caller needs.

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

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

Front-loads the purpose and return shape, then layers matching rules and the dedupe caveat. It is dense and information-rich with no wasted sentences, though the parenthetical lists make it slightly heavier to parse than necessary.

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

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

For a one-parameter lookup with no output schema, the description fully covers purpose, matching edge cases, return keys, and the relationship to the authoritative dedupe path. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 0% for the single source_url parameter, but the description compensates with real semantics: tracking parameters and fragments need not be stripped, and the posting's own sub-paths are normalized. It clarifies what input is acceptable rather than just naming the field.

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

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

Opens with the concrete question it answers ("is this posting already captured?") and names the resource (posting-equality source_url lookup) and the return shape. An agent can immediately tell it apart from siblings like store_extracted_jd, list_jobs, and 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?

Explicitly frames when to use it (before an extraction, to skip work when found=True) and names the alternative that dedupes authoritatively (store_extracted_jd via already_existed). It also states the failure mode: search-results or employer-index URLs match nothing. 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 flag destructiveHint=true and idempotentHint=false, and the description usefully adds the specific destructive consequence: it replaces the application's prior generated cover-letter entry. It does not cover auth requirements, output format, or regeneration limits, but it meaningfully explains what gets destroyed.

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 compact sentences, front-loaded with the action and followed immediately by the replacement warning. Every sentence earns its place with no filler.

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

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

The mutation semantics are covered by annotations plus the replacement note, but with no output schema the description says nothing about what the generated letter looks like or how it is returned, and the tone parameter contract is undefined. Adequate but with clear gaps for a write tool.

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

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

Schema coverage is 0% and there are no enums, so the description must carry the load. It only gestures at 'requested tone' without listing valid tone values, and says nothing about application_id. Both required parameters remain under-specified.

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 (generate) and resource (cover letter) scoped to an application and a requested tone. It clearly identifies the operation; there is no sibling cover-letter tool to be confused with, but the description does not explicitly differentiate from adjacent tools like tailor_application or generate_qa_answers.

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

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

No guidance on when to use this versus alternatives, no prerequisites, and no indication of required application state. The description only asserts what the tool does, leaving the agent to infer context.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the write/creative nature is covered structurally. The description adds genuinely useful context that answers are grounded in the resume and the application's linked referral contact, but it omits return format, cost/latency, and any persistence 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?

Front-loaded with the core purpose, then two supporting sentences with no filler. Slightly verbose in the final clause but every sentence contributes.

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

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

There is no output schema, so the description ideally would explain what the generated answers look like or where they go, which it does not. It is adequate for a generation tool but leaves the return/consumption story and application_id semantics unaddressed.

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 the burden. It meaningfully explains `questions` (the complete list for this batch, including free-form outreach prompts), but says nothing about `application_id`, leaving half the required parameters 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+resource ('Generate a batch of screening-question answers for an application'), which clearly identifies the operation. It does not explicitly differentiate from siblings like list_qa_entries or record_filled_answers, but the purpose is 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?

No when-to-use guidance, no prerequisites, and no alternatives named. It clarifies the content of `questions` and notes that outreach messages surface here as free-form questions, but this is context about inputs, not routing guidance for selecting this tool over its siblings.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the return payload (customized_json plus joined job), which is useful given no output schema, but says nothing about behavior for a missing or invalid ID or any auth requirements.

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

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

Two short sentences, front-loaded with what is retrieved and what is returned; no filler or restatement of the name.

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

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

For a single-entity read tool with one param and no output schema, the description is nearly sufficient — it characterizes the return value and points at a related comparison tool. The only real omission is how to obtain the application_id.

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 says nothing about application_id — neither its format nor that it originates from list_applications/propose_application. With only one parameter this is a small gap, but the description contributes no parameter meaning at all.

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

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

States a specific verb and resource (get one application) and enumerates the payload: the tailored resume (customized_json) and the joined job. That payload description distinguishes it meaningfully from list_applications and from edit/update_application, though it doesn't contrast with other single-entity getters like get_proposal.

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 sentence 'Use compare_ats for before/after scores' routes the agent on an adjacent need, but there is no explicit statement of when to call this tool versus get_application-adjacent siblings (get_proposal, get_final_review) or where the application_id comes from. Usage is implied rather than prescribed.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses consent gating and stripping of `profile.eeo`, that canonical_identity takes precedence over ATS-parsed values, that answers are for verbatim fill with no inference, and that WOTC/signatures/terms are human-only. These are non-obvious behavioral traits an agent cannot infer from the structured fields.

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

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

Front-loaded with the payload summary, and most content earns its place, but the EEO/veteran/gender enumeration is extremely dense and reads like field-level documentation rather than tool-selection guidance. It is long enough that key routing information risks being 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?

With no output schema and no annotation coverage of content, the description must describe returns, and it does so thoroughly, including edge cases (missing county), consent-dependent fields, and identity precedence. An agent has everything needed to call and interpret the result.

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

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

Schema coverage is 0% and neither parameter is described in the schema, so the description carries the burden; it explains that supplying `application_id` or `base` adds employment blocks and skills from the selected resume. However it never clarifies what `base` is (base resume id?) or how the two parameters differ, so half the parameter meaning is still implicit.

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+resource ('Read the user's application-form autofill data') and then enumerates the exact payload (profile fields, employment, skills, canonical_identity, EEO) so it is unmistakable against siblings like get_application or get_career_context. The scope is narrow and self-defining, so an agent can select it 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?

Gives clear conditions ('plus employment blocks and skills from the selected resume when application_id or base is given') and states the operational context ('same feed the Chrome extension's deterministic fill uses, so it supplies real stored values for ATS forms'). It also tells the agent what to do when data is absent ('not guessable', 'left to the user'), though it never names an alternative sibling or an explicit when-not.

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 fully covered by structured data. The description adds value by disclosing what the read returns (full data JSON, render status, metadata), which is useful given there is no output schema. It stops short of describing error/not-found 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?

A single front-loaded sentence with no filler; the payload contents are listed compactly and every clause informs the agent about the call's 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?

With no output schema and only one parameter, the description does the necessary work by naming the returned artifacts. It is nearly complete for a simple read tool; only the slug semantics and failure behavior are absent.

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

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

Schema description coverage is 0% for the single 'slug' parameter, so the description carries the full burden. It implies the slug identifies the resume but never explains the slug's format, source (e.g., from list_base_resumes), or what happens on an unknown slug.

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 ('Get') and resource ('base resume') and enumerates the payload ('full data JSON, render status, and metadata'), so it is clearly distinguishable from list_base_resumes. It does not explicitly distinguish itself from retrieval-adjacent siblings like get_resume_version, but the purpose is 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 statement of when to use this tool versus list_base_resumes, get_resume_version, update_base_resume, or edit_base_resume. No preconditions or exclusions are given; the agent must infer usage entirely from the name.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, yet the description adds real behavioral context beyond them: it never invents facts, metrics, employers or dates, absence from the output means the fact is not recorded, and it deliberately carries no IDs (routing to kb_list_entities / kb_get_entity / kb_list_points). This is substantive disclosure layered on top of the safety profile.

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 what is read and the two output sections before the usage and caveat sentences, so an agent can stop early. It is dense and slightly long, but each sentence (composition, grounding use, no-invention guarantee, ID absence) carries information rather than filler.

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

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

With no output schema, the description must explain the return shape, and it does: `resume` is approved points only while `memory` adds the profile summary, notes, and notes from non-archived entities. Combined with the grounding contract and ID guidance, an agent has everything needed to call and interpret this correctly.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. No misleading parameter hints are 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?

Specific verb+resource (reads the composed career context from the Career KB) with the two returned sections, `resume` and `memory`, explicitly defined. It distinguishes itself from the kb_* siblings by naming them as the ID-bearing tools it is not, and from get_base_resume by framing that as an optional companion.

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

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

States the intended use clearly: grounding for writing about the user's career (LinkedIn posts, outreach drafts), optionally paired with get_base_resume for a specific resume's voice. It names the correct siblings for ID correction, but gives no explicit when-not-to-use condition or exclusion.

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 and destructiveHint=false, so the safety profile is covered. The description still adds value beyond them: the output is 'deterministic' Markdown and it 'does not alter tailoring behavior', a domain-specific side-effect statement. It stops short of explaining generation/refresh behavior, so not a full 5.

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

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

Three short sentences, front-loaded with what is returned, followed by the routing hint and the safety note. Every sentence 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?

An output schema exists, so return values need not be re-explained, and there are no parameters or nested objects to cover. For a simple read-only export, nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; the baseline for a parameterless tool applies. No param information is needed or missing.

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 the exact portable career.md generated from the current Career KB') and explicitly names the sibling it is not ('For structured resume and memory fields, use get_career_context'). An agent can distinguish this from get_career_context without opening either schema.

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

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

Gives the conditions that select this tool ('copy-out, download-equivalent use, or Markdown-oriented grounding') and names the alternative plus the condition that selects it (structured resume/memory fields). Routing is explicit and unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the 404 failure mode and its likely cause, the meaning of duplicate_submitted, and the conditional semantics of base_country.eligible. Its only shortfall is that much of that detail is really return-field semantics rather than operation behavior.

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

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

The payload description is front-loaded in the first sentence and every subsequent sentence adds distinct information (precondition, 404 cause, duplicate_submitted meaning, flags shape, base_country semantics). It is dense and readable, though the long run-on paragraph could be broken into labeled segments for faster scanning.

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

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

With no output schema, the description must carry the return contract, and it does: it enumerates the bundle sections, explains the flags entry shape (question, source, answer, reason, EEO variant), and documents two derived fields. Nothing an agent needs to call and interpret this tool 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% for the single parameter, so the description carries the burden — and it partially does by clarifying that proposal_id means a proposal id, not an application id, which is the common misuse. It adds no format, naming, or sourcing guidance beyond that disambiguation, so it compensates only in part.

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+resource (get_final_review) and immediately enumerates the bundle contents (job summary, score delta, PDF readiness, QA answers, EEO consent flag, blocked items, evidence manifest). An agent can distinguish this pre-approval review artifact from get_proposal or get_application 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?

States the precondition clearly ('Requires an existing proposal') and gives the remediation path plus the exact failure mode (404 usually means propose_application was not called, or an application id was passed instead of a proposal id). It also frames the intended consumer context ('relevant to the user's approval decision'). It stops short of naming an alternative sibling for the adjacent questions, so it is context-rich but not a full when/when-not routing statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the failure mode (error when no report exists yet) and the pointer to run_health_check as the remedy.

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, followed by parameter meaning and return shape in two tight sentences. The inline field list is dense but earns its place given there is no output 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?

With no output schema, the description steps in to enumerate the returned fields and the error case, which is enough to call and interpret the tool. A mention of report freshness/staleness semantics would make it complete.

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

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

Schema description coverage is 0%, so the description must carry the burden and largely does: it explains that `kind` is 'base' or 'application' and `key` is the slug or the application id. Only minor gaps remain (format of the slug/id is not spelled out).

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 (Fetch) and resource (most recent stored health report) plus the scope (base resume or application) and the key constraint ('without re-running it'). It is immediately distinguishable from the sibling run_health_check, 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?

Clearly frames when to use it: to read an existing report rather than recompute one, and it points at run_health_check as the tool that creates a report when none exists. It stops short of an explicit 'use X when you want a fresh score' rule, but the routing is inferable.

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 the safety profile is covered. The description adds genuinely useful context about the payload shape (nested ownership fields: owned_here, owner, handover, pending_requests) and what those fields identify, which goes 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?

Two sentences, purpose front-loaded first, return-shape detail second. Efficient and no padding, though the second sentence is dense with parenthetical field names.

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, so the description must carry the return burden; it partially does by naming the ownership fields. But job_id semantics and the relationship to siblings (get_application) are left unstated, leaving gaps for a lookup tool.

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

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

Schema description coverage is 0% and the description adds nothing about job_id — no format, source, or how to obtain a valid id. With a single undocumented parameter, the description fails to compensate for the schema 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?

States a specific verb+resource ('Get a job') and adds scope detail ('with its most recent application'), which distinguishes it from siblings like list_jobs and get_application. It stops short of explicitly naming alternatives, but the agent can tell what it retrieves.

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 versus get_application, list_jobs, or get_job_search_brief. Usage is only implied by the word 'Get' on a single job_id; no exclusions or prerequisites are stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the bar is lower; the description adds real behavioral context by disclosing that constraints are returned VERBATIM and 'never guessed', that warnings[] appear on contradictions/missing values, that persona text may be empty, and what sync/applying fields mean. It does not cover auth needs or rate limits, keeping it at 4.

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

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

The purpose is front-loaded, which is good, but the rest is a single dense run-on paragraph packed with parentheticals and trailing fragments like 'applying.answer_level is the Screening answers level (facts, history, queued)'. Given there is no output schema the content is largely justified, but the parsing burden is high and the structure could be broken into clearer segments.

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 entire burden of explaining the return payload and does so thoroughly — listing every section, its fields, and edge cases (empty persona, contradictory constraints, null role when sync is off). An agent has everything needed to interpret 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?

The tool takes zero parameters, so per the rubric the baseline is 4; there is nothing to disambiguate and the description correctly focuses entirely on the returned payload instead of inventing arguments.

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

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

Opens with a specific verb+resource ('Read the server-composed job-search brief') and then enumerates its sections, so an agent knows exactly what it returns. It also positions itself against siblings by naming itself the entry point of the agentic job-search workflow and excluding exploration/applying tools from its scope.

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

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

States when to reach for it (the entry point of the capture/scoring/proposal workflow, with a playbook pointer) and draws an explicit boundary ('applying is outside its scope'). It stops short of naming specific sibling alternatives for adjacent needs, so it is clear context without full when-not 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 annotations already covering safety hints, the description adds substantial non-obvious context: every call is recorded (but never the value), the value is exposed to the agent's AI provider, and the user's password is deliberately scoped to job sites. It also pre-empts the odd readOnlyHint=false by explaining the audit side effect, so there is no contradiction. It stops short of describing failure behavior when the preconditions are unmet.

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 what the tool returns, followed by availability constraints, audit/privacy notes, and the return shape. Three dense sentences, all earning their place; the AI-provider sentence is slightly circuitous but adds meaningful warning value.

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

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

There is no output schema, and the description compensates by specifying the return shape {email, password}, plus availability gates and a privacy warning. Complete for invocation; only a note on what happens when the tool is unavailable or the proposal is unapproved 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% for the single proposal_id parameter, so the description carries the burden. It only implies the parameter via 'this proposal's application site' and 'a queued or approved proposal', which conveys the concept but not the id format or source (e.g., from list_proposals). Baseline 3 for a one-param tool with a partial hint.

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

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

States a precise verb+resource: it retrieves the user's saved email and password for job-site accounts tied to a proposal's application site, and names the intended use (creating an account or signing in). No sibling tool does credential retrieval, so it is unambiguously distinct from get_proposal, get_application, and the kb_* family.

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

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

Gives explicit preconditions that act as when/when-not guidance: available only while full automation is on, and only for a queued or approved proposal. The purpose statement also names the concrete situation in which the agent should reach for it (signing in or creating an account on the application site).

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 states that reading the resource mutates it, expiring an overdue pending_review or needs_decision proposal into a terminal 'expired' state. That is a state-changing, effectively irreversible side effect, which directly contradicts the readOnlyHint=true and destructiveHint=false annotations. This is a genuine annotation contradiction.

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

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

Two sentences, zero filler, and the return payload is front-loaded before the critical side-effect warning. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates the returned sections (job facts, application summary, QA entries, evidence manifest) and warns of the expiry transition, which is the most important thing an agent must know here. It is only incomplete in that it says nothing about the proposal_id parameter.

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

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

There is a single required parameter, proposal_id, with 0% schema description coverage, and the description never explains its meaning, format, or where to obtain it. With no annotations or schema text to lean on, the description fails to 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?

States a specific verb and resource ('Get proposal detail') and enumerates the payload it returns (job facts, application summary, QA entries, evidence manifest), which is far more useful than a tautology. It implicitly contrasts with list_proposals via 'detail', but never names that sibling explicitly, so 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?

Usage is only implied: an agent can infer this fetches one proposal by id rather than listing them. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. list_proposals for discovery), so guidance is thin.

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

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

Beyond the readOnly/idempotent hints it discloses concrete behavior: it writes the PDF and per-page PNGs under $MAESTRO_CS_PDF_DIR (or a temp dir), guarantees no inlined base64, and defines how em_dash_found/em_dash_pages are computed and how page_count/page_images degrade when the PDF can't be read. This is unusually rich disclosure of side effects and edge cases.

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

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

Front-loads the core action, then returns, then prerequisites, then environment details, so an agent can stop reading early. It is a dense block rather than bulleted and the return-shape detail is long, but nearly every sentence adds distinct, useful 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 fully enumerates the return object ({filename, path, size_bytes, mime_type, page_count, page_images, em_dash_found, em_dash_pages, artifact_dir?}), the prerequisite, the file destination, and the edge case where the PDF is unreadable. Nothing an agent needs to call and interpret this tool 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 carries the full burden and does so well: it explains that target_type accepts 'base_resume' (slug), 'application' (id), and 'template' (id), and describes what each target returns. target_id semantics (slug vs id) are implied by the per-type parentheticals.

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

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

The description pairs a specific verb with a specific resource ('Save a rendered PDF locally and render one PNG per page') and clarifies the exact scope (the last rendered resume PDF, a template preview PDF). It is immediately distinguishable from the sibling get_rendered_pdf_page_image, which only returns one page's visual bytes.

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 the prerequisite plainly ('Requires an existing render (render_pdf, or validate_template for a template preview)') and routes the agent to the alternative tool when image bytes are needed. It doesn't spell out an explicit 'do not use when' clause, so it falls just short of the fully explicit 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds meaningful behavior the annotations cannot: payload-size rejection above ~1MB, out-of-range page rejection, 1-based numbering, and that only the requested PNG is included. These are real operational constraints an agent must plan around.

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

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

Front-loads the core purpose before diving into parameter and return detail, and each sentence carries distinct information with no filler. It is dense but every clause earns its place; only the long parenthetical clauses make it slightly heavy.

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 the return fields (target_type, target_id, page_number, page_count, filename/path/size/mime, page_image_b64), and constraints are covered. The gap is the unexplained target_type/target_id semantics for a tool that requires both.

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 carries the param burden, yet it only documents two of four: page_number (1-based) and max_dimension_px (default 1024, longest side, larger grows the payload). target_type and target_id semantics, including the three enum values, are left entirely 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 and resource ('Return one rendered PDF page') and immediately distinguishes itself from the sibling get_rendered_pdf by noting it does not change that tool's pre-rendered preview PNGs. An agent can tell what this produces 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 'explicit opt-in visual payload' framing tells the agent this is the deliberate choice for pulling a single page image, and the closing sentence contrasts it with get_rendered_pdf's default previews. It establishes context and the alternative, but never states an explicit trigger condition such as 'use this when you need a page the pre-render doesn't cover.'

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 and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine behavioral value by disclosing what is returned (snapshot plus parent diff), which is not inferable from the schema.

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

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

Two sentences, both front-loaded with the highest-value information (what it returns, then how to source the parameters). 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?

There is no output schema, so the description correctly takes on the job of explaining the return payload (snapshot + diff). Combined with full parameter coverage and annotation-backed safety, only minor gaps remain, such as error behavior for a nonexistent version.

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 the burden, and it does: it defines kind as 'base' vs 'application', explains key as a slug for base or an id for application, and identifies number as the version number from list_resume_versions. It compensates well, though it omits format details such as whether number is 0-indexed or 1-indexed.

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 (Fetch) and resource (one resume version), and further specifies the payload: the snapshot and the diff vs its parent. This clearly distinguishes it from the sibling list_resume_versions, which returns many versions rather than one with a diff.

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 anchors usage to list_resume_versions by telling the agent that kind/key/number come from that list, which is real workflow context. It does not, however, state when not to use this tool or name restore_resume_version as the mutation 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 readOnlyHint, idempotentHint and destructiveHint, so safety is covered; the description adds real signal beyond them — the frozen gap list, that resolutions_json can carry pre-stamped SYSTEM-PLANNED auto-resolutions with provenance, and that tailor_session consumes the saved resolutions. It does not need auth/rate-limit detail for a safe read.

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

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

Purpose is front-loaded and every sentence conveys domain-specific meaning, but the paragraph is dense with jargon and packs downstream usage (retraction, tailor_session consumption, base_anchors) into a single block that is harder to scan than it needs to be.

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

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

With no output schema and no annotation detail on payloads, the description compensates by explaining the returned fields (gaps_json, resolutions_json, status) and the unresolved-gap definition. It is close to complete, missing only the exact status-transition or format conventions.

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 the load for the single parameter, and it does: tailoring_session_id is explicitly defined as the id returned by create_tailoring_session. It does not state the string format, but the origin/linkage is the practically important information.

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

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

States a specific verb (fetch) and resource (tailoring session) plus intent (resume a half-done gap walkthrough). It is clearly distinguishable from create_tailoring_session, list_tailoring_sessions and close_tailoring_session among siblings.

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

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

The 'to resume a half-done gap walkthrough' framing gives clear when-to-use context, and it names the producing tool (create_tailoring_session) and the consuming tool (tailor_session), plus resolve_gaps for retraction. It does not give explicit when-NOT-to-use or exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, so the safety profile is covered, and the description adds real domain context: the returned source differs by engine (Jinja2+LaTeX vs raw .typ), how templates opt into fmt.* knobs, the defaults, and a typst-specific quirk where date_format is always supported server-side. This is meaningful behavior beyond the annotations, though it does not discuss 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?

The purpose is front-loaded in the first clause, which is good, but the body then expands into a long enumeration of fmt.* knobs and defaults that is more relevant to rendering/tailoring than to merely fetching a template. The density is high and could be trimmed or moved, making it verbose for the stated action.

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

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

With no output schema, the description correctly takes on the burden of describing return values and does so thoroughly (source, engine, engine_available, supported_fmt_keys, and the fmt namespace semantics). It is close to complete, with only error/missing-template behavior left unspecified.

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 single template_id parameter has 0% schema coverage, so the description carries the burden, but it never defines the id's format or where it comes from beyond an implicit nod via '(see list_templates)'. It does add substantial context about what a template object contains, which indirectly clarifies the resource, but the parameter itself is only weakly explained.

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 (get) and resource (template) and enumerates exactly what is returned: full source, engine, engine_available, and supported_fmt_keys. It also distinguishes itself from list_templates by referencing it, so an agent can tell the retrieval tool apart from the listing tool without opening schemas.

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

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

The only routing cue is the parenthetical '(see list_templates)', which implies that list_templates supplies the template_id this tool consumes. There is no explicit when-to-use/when-not statement, no prerequisite about needing a valid template_id, and no mention of error behavior for a missing template.

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

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

Annotations already declare the mutation profile (destructiveHint=true, idempotentHint=true), but the description adds real substance beyond them: approved points are the only ones surfaced on resumes/exports, the server does NOT verify user review ('a convention, not enforcement'), and unknown ids fail per-id while the rest proceed. Minor deduction for not stating auth/permission requirements for this write path.

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

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

Purpose and the key scoping constraint are front-loaded in the first sentence, and the response shape is last. It runs dense across several lines and includes a couple of low-yield asides (the record_consent analogy, the slightly tangled 'fails the same way until corrected' phrasing) that could be tightened.

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, so the description supplies the return contract ({results:[{id, ok, state, detail}], next}) including the semantics of next. Combined with the partial-failure behavior, an agent has everything needed to call it and interpret results in a batch 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 carries the load and does: it constrains state to approved|retired, bounds point_ids to 1-500, and discloses that duplicate ids collapse to one result row. These are non-obvious constraints not derivable from the schema alone.

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 (batch-set) plus resource (Career KB point state) and the exact value domain (approved or retired). It also self-identifies as 'the single approval path available over MCP', which distinguishes it from sibling mutators like kb_edit_point and kb_list_points.

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 frames when to reach for it ('the single approval path'), rules out a category of misuse (bulk-to-draft is impossible), and points to kb_list_points for obtaining valid ids. An agent knows both the trigger and the guard rails without opening a schema.

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

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

Adds substantial behavior beyond the annotations: the call invokes the configured LLM provider (cost/latency/external-dependency implication), a model matches or proposes an entity, output lands as drafts needing user approval, and text is stored verbatim as user-owned unverified content. These facts meaningfully extend the readOnly/openWorld/idempotent hints.

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

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

Three tight sentences, front-loaded with the core action, each adding a distinct fact (matching/LLM, drafts+approval, verbatim storage). No filler or repetition 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 2-param, no-output-schema write tool the description covers purpose, behavior, side effects, and the approval gate well. The main residual gap is what the call returns (e.g. created draft point/entity identifiers), which the absence of an output schema leaves undocumented.

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 carries the load, and it does explain both parameters: 'text' is the user's own words stored verbatim, and 'entity_id' forces placement into a specific entity instead of model-matched. It stops short of telling the agent where entity_id values come from (e.g. kb_list_entities).

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 ('Capture free-text career news into DRAFT points') and immediately frames the pipeline role (draft → approval at /career). It is distinguishable from sibling kb_* tools like kb_create_entity, kb_edit_point, and kb_approve_points because it is the ingestion step, not the editing or approval step.

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 context for use (capture free-text career news; pass entity_id to force placement) and describes the downstream approval workflow. It does not, however, compare itself to alternatives such as kb_create_entity or kb_ingest_resume, so the agent gets context but no 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?

Goes well beyond the annotations: it discloses that the write is immediate with no draft gate, that no duplicate is blocked and possible_duplicates hints come back, and that a certificate PDF cannot be created here and must be uploaded via the web UI. These are non-obvious behavioral traits that annotations (readOnlyHint=false, idempotentHint=false) alone would not 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?

Front-loaded with the verb+resource and the kind enum, then progressively adds constraints. Dense but each clause adds a real constraint; a small amount of parenthetical nesting makes it slightly harder to scan than it needs to be.

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

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

For an 8-param mutation with no output schema and 0% schema coverage, the description covers the highest-risk pieces (immediate persistence, no dedupe, kind='extra' nesting, upload limitation). The undocumented side of the parameters (status, notes, date formats) is the remaining gap.

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

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

Schema description coverage is 0%, so the description carries the burden. It does define kind's value set, the free-form detail dict conventions (tech/link/field), and the nested section_key/section_type/section_title requirement for kind='extra', but org, notes, status, start_date and end_date receive no semantic treatment at all.

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

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

States a specific verb (Create) and resource (Career KB entity) and enumerates the concrete kinds it accepts (experience|project|education|certification|extra). An agent can distinguish this from kb_edit_entity and kb_capture without opening either schema.

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

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

Usage is only implied: 'writes immediately and is not draft-gated' contrasts indirectly with the draft/approval flow behind kb_capture and kb_approve_points, but no alternative is named and no explicit when-to-use condition is given. Adequate but leaves the agent to infer the routing against siblings.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false. Beyond that the description adds real behavior: 'Omitted fields are left alone' (partial-update merging), 'writes immediately with no draft gate' (no approval step, no undo window), and 'each supplied value replaces the stored one' (overwrite, not append). That is genuine added context over 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?

Four short sentences, front-loaded with what the tool does, then partial-update semantics, then the immediate-write caveat, then the immutable-field limitation. No filler and nothing buried.

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

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

For a mutation tool with no output schema, the description covers the important gaps: partial update behavior, no draft gate, destructive overwrite, and the kind immutability boundary. Missing only return-value expectations, error behavior on a bad entity_id, and the 'detail' parameter's meaning.

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 carry the load, and it does for most fields: it maps dates, title, org, notes, and status, and supplies the status enum (ongoing|completed|archived) that the schema itself omits. It leaves the 'detail' object parameter and the date string format unaddressed, so it is strong but not 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 (Fix/Edit) and resource (entity), then enumerates the editable field set (dates, title, org, notes, lifecycle status). The 'Kind cannot be changed here — that is a rebuild, not a correction' clause separates it cleanly from the create/rebuild path without the agent needing to open any schema.

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

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

Gives an explicit exclusion (kind changes belong elsewhere) and frames this as a correction rather than a rebuild, which routes the agent productively. It stops short of naming the alternative tool for rebuilds, so it lands below the explicit when/when-not/alternative bar 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?

Annotations only say it is a non-read-only, destructive, idempotent, closed-world write. The description goes well beyond that by disclosing the workflow side effect: editing text regresses the point to DRAFT and removes it from the composed resume and career export until re-approval. That is exactly the consequence an agent must know before mutating.

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

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

Two sentences, zero filler. The action is front-loaded and the consequence statement follows immediately, with the exclusion clause last.

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 3-param mutation tool with no output schema, the description supplies the important missing piece (the draft regression). It omits what happens when both optional fields are null and whether any point state blocks editing, but nothing critical to a correct call is absent.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only names the two optional fields (text, tags) without explaining that null means 'leave unchanged', whether tags replaces or merges the existing set, or the point_id format. The field names align with the schema, so this is adequate but leaves real ambiguity.

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 pair and resource: 'Reword a Career KB point or retag it.' It also draws the boundary against sibling tools by declaring 'Cannot approve, retire or delete a point,' which separates it from kb_approve_points and the other kb_edit_* tools without needing to open their schemas.

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

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

Gives clear context (text vs. tag edits) and names the follow-up route when approval is needed (kb_approve_points or /career). It does not spell out when to prefer kb_edit_point over kb_edit_entity/kb_edit_profile, but the resource noun makes that inference safe.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds real context beyond them: 'Writes immediately with no draft gate' and the wholesale-replacement semantics that justify the idempotent hint. It does not cover failure modes or validation 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?

Three tight sentences, front-loaded with the target and affected fields, then the critical merge semantics, then the side-effect warning. 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, so the description carries the behavioral load, and it does so well for a zero-required-parameter mutation tool: it covers scope, merge behavior, read-before-write routing, and immediacy. Minor gaps remain around input shape hints and error handling.

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 all four parameters are undocumented nullables, so the description carries the burden. It compensates by mapping its four named fields to the four parameters and clarifying the replace-not-merge semantics, though it says nothing about the expected shape of the contact object or skills array.

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 ('Update') and resource ('Career KB profile') and enumerates exactly which fields it touches (contact block, summary, skill groups, notes). It is distinguishable from nearby siblings like kb_edit_point and kb_edit_entity by scope, though it never explicitly contrasts itself with 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?

Gives concrete guidance on how to use it correctly: omitted fields are untouched, supplied fields are replaced wholesale, and current values live in get_career_context (a named sibling to consult first). It lacks an explicit 'use X instead when...' exclusion relative to the point/entity editors.

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine value beyond that by enumerating what is returned (dates, notes, points with id/text/state, documents, activity timeline) and by disclosing the filtering nuance 'archived included, deleted excluded' for used_in_bases.

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

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

One sentence, front-loaded with the core purpose ('Full detail for one Career KB entity'), followed by the return contents. No filler, no repetition 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?

With no output schema, the description usefully enumerates the return payload and its filtering rules, which is exactly what an agent needs for a read-only single-entity fetch. The only gap is the unstated provenance/format of entity_id.

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 there is a single required entity_id, so the description must compensate. It implies the parameter selects 'one Career KB entity' but gives no format, source, or lookup guidance for the id. Baseline adequacy, no added semantics.

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

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

States a specific verb and resource ('Full detail for one Career KB entity') and the singular scoping implicitly separates it from list siblings like kb_list_entities. An agent can tell it is a detail-fetch for a single entity 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?

Usage is only implied by 'for one Career KB entity' – it presupposes a known entity_id but never states where that id comes from (e.g., kb_list_entities) or when to prefer this over kb_list_points or kb_edit_entity. No explicit exclusions or prerequisites are given.

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

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

Goes far beyond the annotations: it discloses draft state, first-write-wins profile seeding, merge-not-duplicate behavior on identical resume_key (matching idempotentHint), atomic 422 semantics, two-pass entity-name matching that can merge differently-spelled names, and that extra_sections are not persisted. This is exactly the behavioral context an agent needs before a mutating call.

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 purpose followed by labeled blocks (HONESTY, ENTITY NAMES) makes the density navigable, and each section adds decision-relevant information. The entity-name matching paragraph is long and borders on internal mechanics, which slightly blunts conciseness, but little is pure filler.

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

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

With no output schema, the description still specifies the return shape {report, next}, what report contains, when next is null, and the 422 failure conditions. Between this, the nested ResumeData breakdown, and the annotation-delimited safety profile, nothing needed to invoke it correctly is missing.

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

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

With only 33% schema coverage, the description carries the load: it gives the resume_key regex ^[a-z0-9][a-z0-9_]*$, spells out the ResumeData shape and section list, notes only contact.name/email are required, and defines brief=True as suppressing the next hint in multi-resume loops. This meaningfully exceeds 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?

States a specific verb and resource – 'Persist one caller-parsed resume into the Career KB' – and immediately disambiguates scope with 'No in-house LLM', signalling the caller owns parsing. Combined with the draft/approval lifecycle, an agent can tell this apart from kb_capture or kb_create_entity 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?

Gives clear lifecycle context: points land as DRAFTS and must be approved via kb_approve_points (or /career), and describes the re-run merge case. It stops short of naming when to prefer this over sibling capture tools like kb_capture, so it is clear but lacks explicit exclusions.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description goes further by disclosing the archive/delete semantics: archived bases are included in used_in_bases, deleted ones excluded, and retired bullets appear only in point_count. It does not discuss pagination or ordering of results, which would be the remaining behavioral gap.

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

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

Front-loaded with the core action and its differentiator, then filters, then return-field meaning. Information density is high and nothing is filler, but the stacked parentheticals make it read as one dense block rather than clearly segmented guidance.

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

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

With no output schema, the description takes on the burden of explaining the return shape and does so: point_count, draft_count, approved_count (with the retired-bullet nuance) and used_in_bases (with archive/delete semantics). Combined with the filter value lists, an agent has everything needed to call and interpret it.

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 schema declares kind/status only as untyped strings with null defaults, so the description carries the full load. It enumerates the exact accepted values for both filters (experience|project|education|certification|extra and ongoing|completed|archived) and signals that both are optional, which is meaning the schema does not 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?

States a specific verb and resource ("List Career KB entities with their IDs") and immediately distinguishes itself from the nearest sibling by noting get_career_context returns prose with no IDs. An agent can tell this apart from kb_get_entity, kb_list_points and get_career_export 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 frames the use case: fetch IDs when you intend to edit, since get_career_context gives prose only. It also explains the two optional filters. It stops short of naming all alternatives (kb_get_entity, kb_list_points) or stating when not to use it, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral value on top: default and max page size, offset-based paging, sort order, and which fields are deliberately omitted from each row. It does not mention row-count/total behavior, 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?

Three front-loaded sentences with no filler; the core action and default paging come first, and the sibling pointer closes it out. Some clauses are densely packed (field list plus omitted-field parenthetical), which costs a little readability.

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

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

With no output schema, the description usefully enumerates the returned row fields and flags what is omitted, and it covers filtering, ordering and pagination. What is missing is minor: no statement of total result count or behavior when `offset` runs past the end.

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 carries the load and does so well: it supplies the enum values for `state` (draft|approved|retired) that the schema lacks, plus `limit` default 50 / max 100 and the paging meaning of `offset`. The only gap is that the column list ('id, entity_id/...') is output-oriented rather than parameter detail.

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 Career KB points across all entities'), plus the ordering ('oldest first') and the optional filter axis. An agent can distinguish it from kb_list_entities and kb_get_entity without opening either schema.

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

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

Explains the unfiltered case (returns first `limit` points) and the paging mechanism (offset), and explicitly redirects to kb_get_entity for per-use port history and merge provenance. It gives clear context but does not state when this should be preferred over the other list-type siblings.

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

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

Annotations declare the safety profile (destructiveHint=false, idempotentHint=true), and the description adds substantial context beyond them: zero LLM calls (deterministic), the exact state change (new material lands as DRAFT points with origin=base_sync), that approval happens at /career, and that the source resume is never modified. It even explains why reruns are safe, going past the bare idempotentHint flag.

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

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

Extremely tight: what it does first, then scoping, then side-effect semantics. Every clause carries distinct information (determinism, draft origin, approval location, no source edits, idempotency) with no filler.

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

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

There is no output schema and only one parameter, so the description carries most of the load and does it well for behavior: state changes, determinism, and side effects are all covered. The remaining gap is the undocumented 'slug' parameter and any error behavior for an unknown slug, which prevents a 5.

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

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

Schema description coverage is 0% and there is one required parameter, 'slug', which the schema does not document at all. The description implies the slug identifies 'one base resume' but gives no format, no examples, and no hint about how to obtain a valid value (e.g., from list_base_resumes). With low coverage the description was expected to compensate and does not.

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 with directionality: 'Sync one base resume into the Career KB.' An agent knows the source (a base resume) and the destination (the Career KB). It does not differentiate itself from adjacent siblings such as kb_ingest_resume, kb_capture, or sync_now, so it stops short of a 5.

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

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

Provides operational guidance ('Safe to rerun — a second call is a no-op when already in sync') which tells the agent repeated invocation is harmless, and 'Never edits resumes' bounds the side effects. However it never states when to choose this over kb_ingest_resume, kb_capture, or sync_now, and gives no prerequisites for the slug. Usage is implied rather than specified.

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, and destructiveHint=false, so safety is covered. The description adds useful behavior beyond that: the output is a thin summary (not full records), ats_score is null when unscored, and paging is limit/offset based.

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 dense sentences, front-loaded with the core purpose and result shape, followed by filtering/paging and then routing. No filler; every clause adds 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 names the returned fields (base_resume_name, ats_score) and their null semantics. It is largely complete for a list tool, though valid filter values and pagination limits remain unspecified.

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 the load, and it maps each parameter to a purpose: status/role_category for filtering and limit/offset for paging. It does not, however, give valid status values or bounds for limit/offset, leaving some ambiguity.

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 your applications') plus the shape of the result ('thin paginated summary array'). It clearly distinguishes itself from get_application(id), which returns the full record.

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

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

Explicitly routes the agent to alternatives: use get_application(id) for the full record and compare_ats for scores. This tells an agent exactly when this tool is the right choice versus its siblings.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the returned field set (slug, display name, summary), which is mild output context — no pagination, ordering, or result-size behavior is disclosed.

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

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

A single front-loaded sentence with the verb and resource first and the field list second. Nothing redundant and nothing padded.

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

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

For a zero-parameter read-only listing tool with no output schema, the description is nearly sufficient; the parenthetical field list partially compensates for the missing output schema. It stops short of stating whether all resumes are returned or how archived ones are treated.

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 an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-parameter 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: 'List all base resumes', with parenthetical field hints. An agent can distinguish it from get_base_resume (singular fetch) and list_resume_versions by the resource noun. It does not, however, explicitly name or contrast with any sibling tool.

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

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

No when-to-use guidance and no alternatives named. With siblings like get_base_resume, list_resume_versions, and kb_list_entities in the same namespace, the description offers no routing signal beyond the tool name itself.

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

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

Adds substantial context beyond the readOnly/idempotent annotations: page-termination semantics ('a page shorter than limit is the last'), item size (~0.8k chars), excluded fields (no raw_text or extracted_json), null semantics for best_ats_score when unscored, and ownership/handover flags. This is exactly what an agent needs to interpret results.

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

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

Front-loaded with the core action and paging rule, then projection contents, then the optional filter and ownership fields. Dense but every clause carries information; the parenthetical field list is long but justified by the absent output 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?

With no output schema, the description fully specifies the returned projection fields, null semantics, and page-boundary behavior, plus ownership metadata. An agent can consume and paginate results correctly without further documentation.

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 carries the burden and does so well: it restates limit default/max, explains offset paging behavior, and gives meaning to without_application. It stops short of documenting edge cases like out-of-range offset, but coverage is strong for three params.

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

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

Specific verb+resource with scope modifiers: 'List stored jobs as a thin summary array, newest first, paged by limit and offset.' It also explicitly distinguishes itself from the sibling get_job ('use get_job for full detail') and implicitly from export_jobs/list_applications.

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

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

Clear routing context: use this for slim summaries and get_job when full detail is needed, plus the 'only jobs without an application' filter condition. No explicit exclusions (e.g., when to prefer export_jobs), so it falls short of a 5.

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

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

The annotations declare readOnlyHint=true and idempotentHint=true, but the description states 'Reading expires overdue pending_review and needs_decision proposals (terminal "expired")' — i.e., invoking this read mutates persisted state. That is a direct contradiction of the read-only/idempotent claims and would mislead an agent about whether repeated calls can change results.

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

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

Front-loads the essential contract (what, ordering, return shape, paging) in the first two sentences, then adds status lifecycle detail. The second paragraph is dense and references internal playbook concepts, but nearly every sentence conveys distinct, non-redundant 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 supplies the return shape ({items, total}), row size, and the proposed_by provenance values, plus full status lifecycle semantics — enough to call it correctly. It omits item field details beyond proposed_by and any error/empty-result behavior, keeping 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 0%, so the description carries the burden and does so: status is 'one status or a comma-separated set' (the schema only says string|null), limit is default 20/max 50, and offset 'pages through total'. It adds real semantics beyond the schema, though it does not cover invalid status values or behavior past the end of the list.

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

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

Opens with a specific verb+resource ('List application proposals'), states ordering ('newest first') and the exact return envelope ({items, total}), which distinguishes it immediately from get_proposal, list_applications, and list_jobs. An agent can tell what this returns 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?

Gives strong operational context: 'accepted' means queued for an apply run, 'pending_review' is awaiting triage, batch apply runs work 'accepted' by convention, and record_triage is named as the accept path. It stops short of an explicit 'use this instead of get_proposal when you need one row' statement, so it is clear context rather than full alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely new behavioral trait, the 'newest first' sort order, but nothing about volume, pagination, or what a missing application returns.

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

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

One front-loaded sentence with no filler; the resource and the sort order are stated immediately with zero 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 one-parameter read-only list tool with no output schema, the description covers the essentials and annotations cover safety. However it omits any indication of return shape or how it relates to the sibling generation and application-listing tools, leaving the agent with a thin picture.

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% for the single application_id parameter, so the schema adds no descriptive text. The phrase 'for an application' only loosely signals that application_id scopes the result; format or constraints are not described, so it partially but not fully compensates 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?

Clear verb 'List' plus a specific resource ('generated screening answers and cover letters for an application'), and it adds ordering ('newest first'). It distinguishes the content from generation siblings like generate_qa_answers/generate_cover_letter only implicitly, 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?

The description states what is returned but gives no when-to-use guidance, no prerequisites, and does not point to alternatives such as get_application or the generate_* tools. Usage is left entirely to inference from the name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and mutability are fully covered without the description. The description adds the shape of returned data (company, careers URL, contact name, notes, applications_count), which is useful since there is no output schema, but it says nothing about scope, volume, or pagination.

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 parenthetical sentence with zero filler; the resource is front-loaded and the returned fields are compactly listed. Every token earns its place.

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

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

For a zero-parameter read tool with full annotation coverage, the description is nearly complete, and the field enumeration substitutes for the missing output schema. It could still state whether all referrals are returned or whether ordering/pagination applies.

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?

This tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering input is accepted and instead documents the output fields, adding marginal value beyond the empty schema.

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

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

States a specific verb (List) and resource (referral contacts), and enumerates the returned fields, so an agent knows exactly what this retrieves. It is distinguishable from sibling list tools like list_jobs and list_applications even without explicit sibling routing.

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 no indication of when to use this over alternatives, no prerequisites, and no filtering or scoping context. It is a bare statement of what the tool returns with no usage guidance at all.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real behavioral context: the list is append-only, ordered 'newest last', and rows are version summaries with number/label/created_at 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-loads the core action, then parameter semantics, then alternative routing. Three tight sentences with no filler; each sentence earns its place.

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

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

No output schema exists, yet the description describes the return rows (version summary: number, label, created_at), defines both required params, and points to the companion tool. 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 carries the burden, and it does so well: it defines kind ('base' vs 'application') and the meaning of key for each ('base-resume slug' vs 'application id'). It even pre-empts confusion with render_pdf's different vocabulary.

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