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 (not read-only, not destructive, not idempotent), and the description adds real value beyond that: file_path bytes are read and uploaded server-side so they never enter model context, invalid source combinations are refused with nothing uploaded, and file type/size limits appear in schema. It does not describe the response after a successful attach, but with annotations carrying the safety profile a 4 is appropriate.

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 with the main action and source constraint front-loaded, and the kind enum placed last. Dense but every sentence carries weight; only slightly more could be trimmed.

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 an output schema absent, the description covers the critical ambiguities: which source parameter to use, the refusal behavior, and the kind enum. The main remaining gap is that proposal_id, step, and label are undefined despite low schema coverage, but their names are largely self-explanatory 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 only 17%, so the description must compensate. It does a good job on the three hardest parameters (mutual exclusivity of image_base64/file_path, the server-side read semantics of file_path, and the kind enum), but it says nothing about the three required parameters proposal_id, step, and label, leaving their meaning to inference. Partial compensation merits a 3.

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

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

The description gives a specific verb and resource ('Attach an evidence image to a proposal') and immediately enumerates the two mutually exclusive source parameters, so an agent can tell exactly what this does without opening the schema. It is clearly distinct from siblings like get_rendered_pdf_page_image or render_pdf.

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

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

It explicitly states the source contract: exactly one of image_base64 or file_path, with both/neither refused and nothing uploaded. That is strong when-to-use guidance for the ambiguous part of the call, but it never states when to attach evidence versus other siblings or any prerequisite context (e.g., proposal state).

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?

Extensive disclosure beyond the annotations: which 422s fire and why (empty entity_ids, unknown role_category, no approved bullets), that unmatched role_label falls back to 'other'/slug other/other_2, that skills and contact always arrive in full from the KB profile and may need trimming, that the summary is dropped without include_summary, and that a job/project with no approved point is omitted. It also documents the {base, next} response and warns that repeating the call mints a second slug — 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 purpose and the hard requirement in the first three sentences, then spends the rest on failure modes and side effects that genuinely matter. It is dense and slightly run-on in the middle (the summary/skills paragraph), but no sentence 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?

There is no output schema, yet the description explains the return value ({base, next}) and even the meaning of next being null. For a mutation tool with six parameters and no structured documentation, the definition supplies everything an agent needs to call it correctly and to interpret the result.

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

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

Schema coverage is 0%, yet the description covers all six parameters: entity_ids (required, non-empty semantics), role_label/role_category (mutually sufficient, strict validation), display_name (never affects the slug), summary (pass a reviewed summary), and include_summary. This compensates fully for the empty schema and adds meaning no schema field could carry.

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?

"Compose a new base resume from selected Career KB entities. LLM-free." states a specific verb (compose), resource (base resume) and source (Career KB entities), which separates it from the sibling create_base_resume that doesn't draw on the KB. It never names that sibling explicitly, so the differentiation is implied rather than stated.

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

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

Gives clear conditions for use: entity_ids must be non-empty because empty would have to mean 'the whole KB', and one of role_label/role_category is required since there is no slug argument. It explains the approval prerequisite (points from kb_ingest_resume are drafts until kb_approve_points). It lacks an explicit 'use create_base_resume instead when...' contrast, but the operational context is unusually complete.

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

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

Beyond the annotations, the description discloses the destructive supersede behavior for existing open sessions, the 409 fatal health gate, and the fact that saved resolutions become unreachable. It further explains enrich's model call and refusal condition based on the writer setting, use_presets' deterministic no-AI fill, and failure behavior when that fill fails.

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

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

The description is front-loaded with the core purpose and destructive behavior, then proceeds logically through workflow, parameters, and response shape. It is long and dense with parenthetical detail, but most content is relevant for a complex tool with multiple behavioral branches.

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 explains the returned session shape, gaps_json.categories ordering, allowed actions per gap, the `next` hint, and `base_anchors` semantics. It also covers important error cases such as 409 health-gate failures, enrich refusals, and stale-session conflicts.

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 low at 25%, so the description must compensate. It gives rich semantics for enrich and use_presets, including side effects, refusal conditions, and preset fill behavior; however, it does not add much detail about the job_id and base_resume identifier parameters beyond their roles in the workflow.

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

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

The first sentence states a specific verb (start) and resource/workflow (gap-analysis tailoring session for a job + base resume), making the tool immediately identifiable. It also distinguishes itself from siblings by naming list_tailoring_sessions, resolve_gaps, and tailor_session in the surrounding flow.

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

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

The description explicitly describes the intended sequence: gather each gap answer, save with resolve_gaps, then call tailor_session. It also names alternatives and conditions, including using list_tailoring_sessions to inspect existing sessions, when add_keyword is allowed versus user_input/attach_project/skip, and when enrich or use_presets should be used or avoided.

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 destructive=true, readOnly=false, and idempotent=false. The description adds valuable behavior beyond that: it preserves prior edits, falls back only when customized_json is absent, clears stale pdf_path/tex_path, and says applied[].name echoes the touched entry.

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 key framing with "INCREMENTAL FIX" and proceeds through fallback, usage, op vocabulary, exact field names, indexing, response, and file invalidation. It is dense but every sentence carries useful context for a complex 16-op 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?

Covers the core behavior, fallback, response echo, and stale-file handling well for a destructive complex tool with no output schema. It is not fully self-contained because full op shapes must be read from the sibling edit_base_resume description.

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

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

With 50% schema description coverage, the description meaningfully compensates by specifying exact op keys (`kind`, `index`, `value`) and 0-based indexing into the full array including disabled rows, not PDF ordinals. It still delegates full op shapes to edit_base_resume and does not describe application_id, though that parameter is obvious.

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: applying typed edit ops to an existing application's CURRENT tailored resume (customized_json), preserving prior edits. It distinguishes the resource from base-resume editing and from creating duplicate 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?

Explicitly says it is suited to refining or retrying a tailored resume after inspecting PDF previews, and explains the base-resume fallback when no customized_json exists. It references edit_base_resume for the op vocabulary but does not fully state when to use that sibling instead or when not to use 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?

Goes well beyond the annotations by disclosing that the tool re-renders the PDF, that every response carries render_error (non-null = stale PDF), that ops write implied first-person text and otherwise 400 with nothing written, and that expected_content_hash supports concurrency checks. These are the mutation side effects an agent needs and are not in 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?

Front-loads the core distinction and index convention before the op list, and the op list is dense but each line earns its place. There is mild duplication between the description's kind list and the `ops` schema description, which keeps it from being maximally tight.

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

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

With no output schema, the description still tells the agent what comes back (`applied` echo and `render_error`), and it covers validation and index semantics. The undocumented `slug` param and an incomplete picture of the full response shape are the only shortfalls.

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%, and the description carries the burden for `ops` by enumerating every kind's shape, the <sec> enum values, the ExtraSection key/entries-or-bullets constraint, and the move_extra_section key-immutability rule. The `slug` parameter is never explained in either place, which is the remaining 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 ('Apply typed edit ops to a base resume') and immediately distinguishes it from the sibling update_base_resume, which replaces the whole body. An agent can tell the two apart 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 says to use replace_entry for field-level changes on one entry versus update_base_resume for a whole-body PUT, and states indices are 0-based into the FULL array as returned by get_base_resume, never PDF order. It also names the failure conditions (bad index/category/key → error).

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 readOnly/idempotent/non-destructive, yet the description adds real behavioral context: one view per call, invalid filter/limit combinations are refused, and 'nothing is read' in that failure case. That is genuine value beyond the annotations. It doesn't mention cost, pagination, or empty-result behavior, so not 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 core behavior and the view enumeration, then filter scoping, then the sibling pointer. It is dense and telegraphic but every sentence adds information; the phrasing is compressed enough to be slightly harder to parse than ideal.

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 plus the richly documented view enum cover what each view returns, which filters are honored, and the failure mode. An agent can pick the right view and call it correctly without further information.

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 20% (level, limit, role_category and employment_type are undocumented in the schema), so the description must compensate, and it does: it explains the filter parameters' scope per view and gives the 1-100 bounds on limit. The per-view return semantics live in the view enum description rather than here, which is fine but leaves the text dependent on the schema.

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

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

The description states the resource (saved jobs and their match scores) and the shape of the output (one chart's rows, one view per call) and enumerates the six named views. It differentiates from the sibling explore_gap_frequency by routing gap-recurrence questions there. The verb is only implied ('as one chart's rows') rather than stated directly, which keeps it just below the top mark.

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 explicitly which filters apply to which views ('role_category, level and employment_type filter the jobs for every view but fit_distribution'), what limit applies to, and that unsupported filters are refused. It also names the alternative tool for gap-frequency questions, so an agent knows both when to use this tool and when not to.

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?

Adds substantial traits beyond the annotations: it errors when no API key is set, it overwrites the prior generated entry (concretely defining what destructiveHint covers), and it returns 409 when the writer setting conflicts. These are exactly the preconditions an agent needs before invoking.

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

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

Three sentences, front-loaded with the action, then prerequisites, then failure modes and the sibling contrast. Dense but every clause carries information; the parenthetical error note is slightly parenthetical-heavy but not wasteful.

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

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

No output schema exists, and the description implies a stored letter but doesn't say what the call returns (letter body, id, or entry reference). Otherwise preconditions, side effects, and refusal behavior are all covered for a two-param generation 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 both params are bare 'string' fields, yet the description only gestures at 'tone' without listing valid tones or noting format, and says nothing about application_id beyond context. With the schema doing nothing, the description needed to carry this and largely did 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 ('writes a cover letter for an application') plus the key qualifier 'Maestro's AI', immediately separating it from store_cover_letter. An agent can tell what it produces and that generation is LLM-backed.

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

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

Names the alternative (store_cover_letter, 'no LLM call') and the condition that blocks this tool (writer setting says agent app writes, checked via get_setup_status), plus the missing-API-key prerequisite. It stops short of saying which situation positively favors this tool, but the contrast is clear enough to route correctly.

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 real context beyond annotations: requires the user's API key and errors without it, grounded in the resume and linked referral contact, and 409 refusal tied to get_setup_status. Does not mention latency/cost of the LLM batch or batching limits, but covers the main behavioral traits.

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 and parameter clarification, with backticked parameter names aiding scanability. Dense but nearly every sentence carries routing or behavioral 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 an open-world, non-idempotent mutation with no output schema, it covers auth prerequisites, grounding sources, refusal conditions, and the sibling alternative. Little is left ambiguous, though return/format expectations 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?

With 0% schema description coverage, the description usefully clarifies that `questions` is the complete list of questions to answer in this batch, and shows the kind of free-form prompts accepted. `application_id` is left implied as the target application.

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 ('writes a batch of screening-question answers for an application') with the actor (Maestro's AI) and scope. It is clearly distinguishable from store_qa_answers, which is described as storing caller-written 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?

Explicitly names the alternative (store_qa_answers for answers the caller wrote, no LLM call) and states a when-not condition (refused 409 when the writer setting says the agent app writes). Lacks a crisp positive 'use when' statement, but the routing is clear.

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

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

Annotations already declare readOnlyHint, 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?

Despite annotations already covering readOnly and idempotent behavior, the description adds substantial behavioral detail: EEO values are returned only under active consent, otherwise stripped; returned EEO answers are verbatim stored answers with no inference allowed; missing values are not guessable; and canonical identity takes precedence over ATS-parsed values.

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 opening purpose is front-loaded, but the body is a dense run-on with nested parentheticals. Much of the EEO and consent detail is valuable, but the structure could be tightened or bulleted for easier parsing.

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 full burden of explaining returned data, and it does so thoroughly: response labeling, canonical identity precedence, conditional EEO consent behavior, and edge cases such as missing values are all covered.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented `base` and `application_id` parameters. It does explain that employment blocks and skills come from the selected resume when either parameter is given, but it does not define the difference between `base` and `application_id` or explain null/default behavior.

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

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

The description opens with a specific verb and resource: "Read the user's application-form autofill data." It then enumerates the profile contents and distinguishes this read operation from the sibling mutation tool `set_autofill_profile`.

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

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

It gives clear usage context: this is the feed for the Chrome extension's deterministic fill and the source of truth for form identity fields. It also states important exclusions such as WOTC, signatures, and terms being human-only, though it does not explicitly compare when to use this versus other sibling read tools.

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

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

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 read-only and idempotent, but the description adds substantial non-redundant behavior: what 'resume' contains (approved points only), what 'memory' adds (profile summary, notes, non-archived entity notes), that markdown output is deterministic and matches the web export, and the critical constraint that neither format carries IDs. That last point materially changes how an agent would sequence calls.

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 action and the format branch, then two clearly labelled per-format paragraphs. Slightly padded at the end — the 'never invents facts, metrics, employers, or dates' sentence is a useful grounding constraint but is stated at length, and the no-IDs point is repeated from context.

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 describe return contents — and it does for both formats, including what is excluded from 'resume'. Combined with the ID caveat and the grounding-use framing, an agent has everything needed to call this correctly.

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

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

Schema coverage is 0% and the enum values carry no descriptions, so the description must carry the burden — and it does. It documents both enum values, restates the default, and contrasts the two outputs semantically ('json' = assembled views, 'markdown' = exact portable career.md).

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 user's career record from the Career KB') and immediately defines what the output is in each format. It is clearly distinguishable from siblings like kb_get_entity (single entity), kb_list_points (IDs), and get_base_resume (a different artifact).

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 intended use ('grounding for writing about the user's career... optionally beside a base resume for its voice') and routes correction work elsewhere ('the profile set's career history tools return the IDs needed to correct anything'). It stops short of naming that sibling tool or stating an explicit when-not-to-use case, so it's clear context without full 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 declare readOnly/idempotent/non-destructive, but the description adds substantial semantics beyond them: what `approval_recorded` vs `eeo.consent_recorded` mean, what `duplicate_submitted=true` implies for the approval decision, what `flags` contains (question, source, answer, reason), and when `base_country.eligible` is false. That is exactly the contextual layer structured fields don't 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?

Front-loaded with the bundle contents before the field semantics, and every sentence adds information. Slightly dense/run-on in the error-handling portion, but no filler.

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

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

No output schema exists, so the description carries the return-shape burden — and it does, defining the bundle's fields, error meanings, and edge-case flags. Nothing an agent needs to call this correctly and interpret the result is missing.

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

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

Schema coverage is 0% for the single parameter, so the description must compensate — and it does by clarifying that proposal_id must reference an existing proposal and by warning about confusing it with an application id. It stops short of stating where to obtain a proposal id (e.g., list_proposals), so not a 5.

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

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

Opens with a specific noun bundle ('Compact final-review bundle') and enumerates its contents (job summary, match score delta, PDF readiness, QA answers, blocked/manual items, evidence manifest). An agent knows exactly what comes back. It doesn't explicitly contrast with sibling get_proposal, so sibling differentiation is only implied.

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

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

States the precondition ('Requires an existing proposal') and interprets the failure mode: a 404 usually means propose_application wasn't called (which accepts application_id to late-link) or an application id was passed instead of a proposal id. It also frames the context as feeding the user's approval decision. No explicit 'use X instead' exclusion, hence not a 5.

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

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

Annotations already declare readOnlyHint, 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 read-only/idempotent safety, but the description adds substantial behavioral detail: warnings are never guessed, work-auth values are verbatim, persona may be empty, failed runs do not count toward last_runs, sync.role is null when off, and work_auth_market is kept for one release. This is exactly the extra context the annotations do not provide.

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

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

The main purpose is front-loaded in the first clause, and every sentence describes return semantics or workflow scope. The paragraph is dense and could be easier to scan as a list, but given the absence of an output schema, the length is largely justified.

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 carries the full burden of explaining what the brief contains, and it does so thoroughly: profile constraints, persona, resume summaries, role mix, skills, build areas, referrals, counts, sync state, and answer level. Safety behavior is already covered by annotations.

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

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

There are zero input parameters, so the baseline is 4. The description instead spends its space explaining return-field semantics, which is valuable but not part of the input-parameter dimension.

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

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

The description opens with a specific verb and resource ("Read the server-composed job-search brief") and enumerates the exact contents, so an agent can tell it apart from sibling tools like get_career_context or list_jobs without opening a schema. It also names its role as the entry point of the workflow.

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

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

It explicitly states when to use it — "the entry point of the agentic job-search workflow" — and defines a boundary: "applying is outside its scope." However, it does not name sibling alternatives or explicit when-not conditions beyond that boundary.

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?

Goes well beyond the readOnlyHint annotations by disclosing real behavioral consequences: with writer="agent", AI-writing tools refuse with 409 and the agent must write and persist via the matching store/add tool; with writer="maestro", the user's ai_key is required. It also states that the AI key, writer, and default resume design are app-set and never appear as a next step, preventing a whole class of wasted calls.

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 a single dense sentence enumerating returns with parenthetical explanations. Every clause carries information, but the nested parentheses and run-on structure make it 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?

There is no output schema, so the description must carry the full return contract, and it does: it names and explains ai_key, writer, demo_bases, next_step (with its {step, tool_set, says} shape and null case), tool_sets, and steps. It also explains the downstream 409 behavior an agent will hit, which is exactly the context needed for a zero-param orientation 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?

The tool takes zero parameters, so the baseline is 4. The description instead spends its space on return-value semantics (writer enum meanings, demo_bases being slugs of shipped demos, next_step being null when nothing remains), which is useful but does not add anything about parameters since there are none.

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 ('where this user's Maestro setup stands') and adds the audience/trigger ('for an agent starting fresh'). The enumerated return fields (ai_key, writer, next_step, tool_sets, steps) make it clearly distinct from siblings like run_health_check or get_career_context.

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

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

The phrase 'for an agent starting fresh' plus the next_step field implicitly tells the caller this is the orientation call before doing setup work. It does not name an explicit alternative or exclusion, so it falls short of a 5, but the usage context is clear enough to route an agent correctly.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds real context beyond that: fields may be empty, the presets are user-owned and immutable via tools, and the server enforces specific rules (unproven skills only in a skills list, resume lines in first person, saved keywords land). The rule list is partially about tailoring generally rather than this read call, so it's helpful context rather than precise return semantics.

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 returned and in what shape, which is the highest-value information. The trailing sentences about server rules and gap-walking drift into workflow guidance that is only loosely tied to a read-only getter, adding length without tightening the tool's own contract.

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

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

No output schema exists, and the description compensates by enumerating the three returned fields and their sub-shape, noting emptiness is possible, and clarifying that the agent may explain or work around the presets. Combined with annotations covering the safety profile, an agent has what it needs to call and interpret this tool 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?

Zero parameters, so the baseline is 4; nothing to document. The description productively spends its space describing the returned structure (presets array with key/on/means, instruction, persona) instead of parameters, which is the useful detail here given there is no output 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+resource: it returns the user's Quick tailor presets as structured data (switches, on/off, plain meaning), plus the per-tailor instruction and persona text. It distinguishes itself from set_persona and the create/resolve siblings by noting the presets are user-set in the app and no tool mutates them. Slightly muddied by extending 'options' to include persona/instruction, which overlaps conceptually with set_persona.

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 routes the agent: use create_tailoring_session with use_presets to follow these presets, or run a custom tailor that walks gaps and saves via resolve_gaps. It explains the downstream consumption rather than an explicit 'call this first when…' rule, but the alternatives and their conditions are named.

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

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

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?

Beyond the annotations (which only say non-read-only, non-destructive, non-idempotent), the description discloses the acceptance rules — analogue/direct require a verbatim ≥3-word quote or the level is downgraded to adjacent, measure questions survive only if the target is in the bullet's own words — plus rejection of non-pending ids, storage under the client's name, and the 409 conflict condition.

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?

Every sentence earns its place and the core effect leads, but the prose is packed into long run-on sentences (the opening sentence alone carries two clauses plus a parenthetical), which makes it denser 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?

There is no output schema, yet the description explains the return value — the rebuilt report with the same fields as run_health_check plus accepted [{id, level as stored}] and rejected [{id, reason}] — and covers error behavior, so an agent has everything needed to call it 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 description coverage is 0%, so the description must carry the load, and it does: kind is 'base' or 'application', key is the slug or application id, and classifications is the list from run_health_check's judging.prompt output shape with one entry per pending id and enumerated level values (direct, analogue, adjacent, implied, unaddressed).

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

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

It states a specific verb and resource — stores evaluations of pending resume bullets, then rebuilds the health report — and situates it against the sibling run_health_check by naming the exact condition under which the judging is delegated to the client. An agent can distinguish it from run_health_check and get_health_report 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?

The when-to-use condition is explicit: it applies while Maestro's own model does not judge (no model key set, or the agent app writes), and the exclusion is spelled out too — a 409 fires while Maestro's own model judges. It also points the caller at judging.prompt from run_health_check as the source of the input shape.

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: drafts are invisible to resumes/exports until approved, text is unverified, there are dash-normalization rules, a 400 for first-person phrasing with nothing stored, dedupe skipping, and a 404 for unknown entities. These are consistent with readOnlyHint=false, destructiveHint=false and idempotentHint=true (repeat calls add nothing), though idempotency could have been tied explicitly to that annotation.

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 and information-dense with no filler, but the store-time rules paragraph is long and reads like spec text rather than selection guidance. It is defensible because these rules change what a caller should send, yet the definition 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?

With no output schema, the description fully documents the return payload ({entity_id, entity_title, point_ids, skipped}) and the error modes. For a two-parameter draft-creation tool, an agent has everything needed to call it 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 only 50% and entity_id has no schema description, but the text compensates by explaining that entity_id must be an existing entity (404 otherwise) and where to get ids. For points it adds content-level validation rules (dash handling, first-person rejection, dedupe) beyond the schema's 1-50/1000-char limits.

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 (add bullets to an existing Career KB entity as DRAFT points) plus the key mechanism (stored as-is, no LLM splitting). It explicitly distinguishes itself from kb_capture by noting the missing model step, so an agent can tell the two apart 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?

Names the alternatives and the conditions that select them: kb_capture when free text needs splitting, kb_approve_points (or /career) to move drafts out of draft state, kb_list_entities to resolve ids, kb_create_entity for a new entity, kb_groom_entity for near-duplicates. Usage is fully routed rather than inferred.

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

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

Goes well beyond the annotations (which only say non-readonly, idempotent, non-destructive): it discloses that approval is a convention not server-enforced, that repeats collapse to one row, that partial failures are per-id with the rest proceeding, and that failed ids keep failing until corrected. It also explains the response envelope and the meaning of 'next'.

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

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

Front-loaded with purpose and scope, then constraints, then response shape — logical ordering with no filler sentences. Slightly dense and the response-shape paragraph is verbose, but every segment carries information an agent needs.

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 envelope ({results:[{id, ok, state, detail}], next}) and the semantics of 'next', plus error-path behavior. For a one-parameter batch mutation tool this leaves nothing material 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 burden: it gives the 1-500 range for point_ids, the deduplication behavior, and what happens with unknown ids ('ok=false detail="not found"'). It does not say where ids come from in the schema itself, though it points at kb_list_points as the source, which largely compensates.

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 ('Batch-approve Career KB points') and immediately explains the downstream effect: approved points are the only ones appearing on composed resumes and the career export. It also explicitly contrasts with kb_retire_points, so an agent can separate the two KB mutation tools 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?

Says this is 'the single approval path available over MCP' and names kb_retire_points as the alternative for retirement, plus points to kb_list_points as the way to obtain current ids. Clear usage context, but there is no explicit statement of prerequisites (e.g. that points must exist first, or what to do if the user has not reviewed them beyond the convention note).

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), it discloses the API-key requirement and its failure mode, the 409 refusal condition tied to another tool, the fact an LLM call is made and may create a new entity, that output is unapproved drafts surfaced at /career, and that content is unverified user words. That is exactly the behavior an agent needs before invoking a mutating, non-idempotent tool.

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

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

Front-loaded with the core action and state, then prerequisites and the alternative tool. Dense with parenthetical asides ("(with none set it returns an error)", "(get_setup_status)") that add value but make it slightly cluttered; still no wasted sentence.

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

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

For a 2-parameter mutating tool with no output schema, it covers auth, error/409 behavior, draft lifecycle, where approval happens, and the sibling alternative. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0%, so the description must carry parameter meaning: it explains entity_id's semantics (force placement rather than letting AI match) and characterizes text as free-text news stored verbatim as the user's own words. The text parameter's expected granularity (a news item vs. a full bio) is only loosely implied, keeping it short of a 5.

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

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

"Capture free-text career news into DRAFT points" is a specific verb plus resource plus state (draft), and the description explicitly contrasts it with kb_add_points (no LLM call) and kb_edit_point/kb_approve_points territory. An agent can distinguish it from the many sibling kb_* tools without opening any schema.

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

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

It gives when-to-use (free-text capture that needs AI entity matching), when-not (use kb_add_points for bullets the caller already wrote), a pre-condition (get_setup_status writer setting, else 409), and an override path (pass entity_id to force placement). No inference is required.

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

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

Beyond the annotations it discloses the key side effect (losers retired and folded as wordings), that resumes are never edited, full reversibility, the convention-not-enforcement gate, the 400 refusal cases (cross-entity, retired/cannot-confirm keeper, user-stopped loser, already-folded keeper), the loser-moves-to-keeper rule, and the return shape. This is consistent with destructiveHint=false and idempotentHint=true.

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 in sentence one, then behavior, reversibility, and error cases follow. The long error sentence packs several conditions together and is the densest part, but nothing is wasted.

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

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

No output schema exists, yet the description documents the return value ({keeper, repointed}), reversibility, limits, and failure modes. For a 2-param destructive-adjacent merge tool, an agent has everything needed to call it correctly and interpret the result.

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

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

With 0% schema coverage the description carries the burden: it defines keeper_id as the surviving bullet and point_ids as 'the others, not the keeper', and adds the 1-50 constraint. It could go further on ID format, but it meaningfully compensates for 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?

The first sentence gives a precise verb and resource: fold Career KB points into a keeper, retire the rest as wordings. It explicitly delineates the keeper vs. point_ids roles and sets it apart from kb_retire_points and kb_merge_entities by the 'same entity required' 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?

It states the reversibility path ('/career → Make its own bullet') and frames the grouping as the user's decision with a convention gate matching kb_approve_points, giving clear context on when/how it applies. It stops short of naming a concrete alternative sibling for a different case (e.g. kb_merge_entities), so it's not a full when/when-not map.

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?

Adds substantial context beyond the annotations: text changes revert the point to DRAFT and drop it from the composed resume and career export until re-approved, which explains the destructiveHint. It also discloses the input-normalization rules (dashes converted, third-person lines rejected with a 400) that no structured field carries.

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 action, then consequences, then exclusions, then normalization rules — a sensible ordering. It is dense and the final sentence is slightly overloaded, but every clause adds operative 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?

No output schema exists, and the description covers the mutation's side effects and failure mode (400) but not what a successful call returns. For a 3-parameter destructive edit, the safety and lifecycle story is otherwise 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 must compensate, and it does: 'text' carries the dash-normalization and third-person-400 rules, and 'retag it' clarifies that tags are a replaceable set. point_id is left implicit, but it is self-evident as the required key.

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: 'Reword a Career KB point or retag it', naming both editable fields. It is clearly separable from siblings like kb_add_points, kb_combine_points, and kb_retire_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?

Explicit exclusion — 'Cannot approve, retire or delete a point' — routes agents to kb_approve_points for re-approval, which is the key follow-up. It doesn't discuss when to prefer this over kb_combine_points or kb_groom_entity when restructuring content, so not quite a full when/when-not map.

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 well beyond the readOnly/idempotent annotations: deterministic zero-LLM scoring, the 0.80 cosine threshold, exclusion of retired and user_cannot_confirm points, subtraction of user-marked 'Not the same' pairs, and the keeper precedence rule (approved > most recent > longest). It also discloses the degraded path (compared_wording=false, empty clusters) when the embedder cannot run — an important failure mode not visible in 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?

The core action, determinism, and propose-only nature are front-loaded, then the return shape and keeper rule follow. It is dense and leans on payload-field enumeration ('{id, text, state, origin, provenance, usage_count, best_score}') that adds bulk, but nearly every sentence carries operational 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 documents the cluster return shape, keeper rule, and degraded behavior — an agent can interpret results correctly. The only real gap is how to source entity_id, which is left implicit.

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 one required parameter with 0% schema description coverage, so the description must carry it. It repeatedly frames the scope as 'the entity's active points', which lets an agent infer entity_id identifies the target entity, but it never states the identifier's form or how to obtain it (e.g., via 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 ('Similar bullets on one Career KB entity, clustered, with a proposed keeper') and immediately names the downstream siblings it feeds into. An agent can distinguish it from kb_combine_points, kb_retire_points, and kb_list_points 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?

Explicitly frames the tool as propose-only ('nothing is written') and routes the agent onward: kb_combine_points for one claim in other words, kb_retire_points for a similar but stale point. This is a clear when-to-use / what-to-do-next mapping against the alternatives.

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

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

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?

The annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, and the description goes well beyond them: it explains exactly how point_count, draft_count and approved_count relate to each other, including the edge case of retired bullets and bullets combined into another being counted nowhere. It also spells out the inclusion rule for used_in_bases (archived included, deleted excluded), which is non-obvious behavior an agent could not infer.

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 sibling distinction are front-loaded, and every sentence carries information. The dense parenthetical about bullet counting is justified but somewhat hard to parse in a single pass, which keeps it just short of a 5.

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

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

There is no output schema, so the description must describe the return shape — and it does, naming the per-item fields (point_count, draft_count, approved_count, used_in_bases) and their inclusion semantics. With only two optional filters, nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 0% and the schema declares both filters as unconstrained strings, so the description carries the full burden — and it does, enumerating the valid kind values (experience|project|education|certification|extra) and status values (ongoing|completed|archived). Without this text an agent would have no way to know legal filter values.

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

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

The description states a specific verb+resource ('List Career KB entities with their IDs') and immediately distinguishes the tool from its closest sibling, get_career_context, by explaining that the latter returns prose without IDs. An agent can tell exactly what it gets here without opening the schema.

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

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

It names an explicit alternative (get_career_context) and the condition that selects this tool instead ('IDs needed to edit'), which covers the main routing decision. It does not, however, position itself against other KB listing tools such as kb_list_points or kb_get_entity, so the guidance is clear but not exhaustive.

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 carry destructiveHint/idempotentHint, but the description goes well beyond them: it enumerates what migrates (bullets in all states, evidence documents, resume-copy records), what is destroyed (title, status, creation record, colliding values), and says outright 'There is no unmerge'. It also discloses failure conditions with status codes (400 archived keep_id, 404 unknown id, 409 concurrent merge), which the annotations do not cover.

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 critical fact ('merge_id goes, keep_id stays') and the duplicate-cure framing are front-loaded, and the paragraphs are logically ordered: effect, field-level rules, losses, refusal codes. It is dense rather than padded, though the run-on parentheticals (bullets in every state, end-date exception) make it longer and harder to scan than an ideal version.

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 destructive two-param merge with no output schema, everything an agent needs is present: direction of the fold, field-by-field conflict resolution, irreversible losses, error conditions, and the return value ('returns keep_id's detail, kb_get_entity's shape'). Nothing material is deferred to an unstated assumption.

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 param meaning and it does: keep_id is the survivor and keeps its title/dates/status/notes while absorbing blanks and missing detail keys, merge_id is consumed and its contents moved. The blank-filling rule and the ongoing-end-date exception give semantics far beyond two bare strings.

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 and resource ('Fold one Career KB item into another of the same kind') and immediately fixes the direction with 'merge_id goes, keep_id stays'. It also names the sibling that handles a different part of the problem (kb_combine_points) and the read sibling whose shape is returned (kb_get_entity), so no ambiguity remains.

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 target scenario is explicit ('the cure for a duplicate an import split off'), the alternative is named for the adjacent job ('one both items carried is there twice afterwards (kb_combine_points folds them into one)'), and the exclusions are enumerated as a refusal list. It adds an operational instruction to the agent too: the merge is the user's decision and the server does not verify consent, so the agent must confirm before calling.

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: discloses that existing resumes keep their text, that the action is reversible from a specific UI location, and that review is not server-enforced. Per-id outcome semantics (unknown ids return ok=false detail="not found" and the rest still proceed) are exactly the kind of behavior an agent needs before mutating state, and the idempotent hint is consistent with "repeats collapse to one result row."

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 effect and reversibility, then moves to limits and response shape. Dense but every clause carries information; the nested parenthetical ("a convention, not enforcement, the same gate as kb_approve_points") is slightly awkward but 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?

A single-parameter mutation tool with no output schema, yet the description covers the state change, reversibility, batching limits, per-id error behavior, and the response envelope including the `next` field. 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 coverage is 0% for the single `point_ids` array, but the description compensates with cardinality bounds (1-500), de-duplication semantics, and per-id failure behavior. It stops short of describing the id format or where ids come from (presumably kb_list_points).

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 ("Batch-retire Career KB points") plus the exact effect (no longer offered to resumes and the career export, while existing resume text is preserved). This clearly separates it from siblings like kb_list_points, kb_edit_point, and kb_approve_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?

The description gives clear operating context: reversibility via /career "Use again" and the fact that the server treats review as a convention rather than enforcement, mirroring kb_approve_points. It does not, however, explicitly say when to choose this over an alternative (e.g., deleting vs retiring a point).

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

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

Goes well beyond the annotations: zero LLM calls, new material lands as DRAFT points with origin=base_sync, the 0.80 cosine dedup rule that keeps existing wording rather than adding a duplicate point, the explicit 'never edits resumes' guarantee, rerun no-op semantics, and the compared_wording=false fallback when the embedder fails. These are exactly the side effects an agent needs before calling a write tool.

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

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

Front-loaded with the one-line purpose, then the side-effect contract in descending order of importance. The final sentence about compared_wording is dense but conveys a real edge case; no sentence 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?

There is no output schema, and the description compensates by describing what the call produces (draft points, wording merges, compared_wording flag) and what it does not do (edit resumes, duplicate on rerun). For a one-parameter, idempotent write tool this covers everything an agent needs beyond the slug ambiguity.

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

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

Schema coverage is 0% and the single parameter 'slug' is completely undocumented in the schema. The description only implies it names 'one base resume'; it never says whether the slug is a base-resume slug or a KB entity slug, nor what format it takes. With one required identifier and no other source of truth, this gap is significant.

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: sync one base resume into the Career KB. That is clearly distinct from edit_base_resume or kb_edit_point, but the description never distinguishes it from the similarly named siblings kb_ingest_resume, kb_capture, kb_add_points or sync_now, so the agent must infer which entry point produces draft points from a base 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?

Usage is only implied by the operation itself (syncing a base resume yields drafts the user approves at /career). There is no explicit statement of when to prefer this over kb_ingest_resume or sync_now, nor any exclusion or prerequisite. The 'safe to rerun' note helps operationally but is not routing guidance.

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

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

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 readOnly=true, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely useful domain context beyond that: archiving hides a resume from scoring and pickers without deleting it, and archived entries carry archived_at. It does not mention ordering or pagination of the list.

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

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

Front-loaded with purpose and return fields, then the filtering behavior, then a tight parenthetical defining archiving. Every sentence earns its place; the nested explanation of archiving is slightly dense but still efficient.

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

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

No output schema exists, and the description compensates by naming the returned fields including archived_at. For a one-parameter read tool this is nearly complete; only list ordering/limits are unaddressed, which is minor.

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

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

Schema coverage is 0% and the single boolean has no description in the schema, so the description must carry it. It does so fully: explains the default (only pickable), exactly what include_archived=true adds, and the extra field those entries carry.

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 base resumes) plus the return fields (slug, display name, summary), which makes it clearly distinct from get_base_resume or list_resume_versions. It never names a sibling explicitly, so an agent must infer alternatives from the names 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 guidance for the single decision point: default returns only pickable resumes, include_archived=true adds archived ones. Clear usage context, but no explicit statement of when not to use it or which sibling to reach for instead (e.g. get_base_resume for detail).

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?

The annotations already establish that this is a safe, idempotent read operation. The description adds useful behavior beyond that by stating the results are newest first and include both model-generated and caller-stored entries, but it omits pagination, result size, and whether full text or metadata is returned.

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