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

Goes well past the annotations by disclosing per-action behavior: start is read-only and repeatable, read authenticates with a locally stored app password the agent never sees and changes nothing, mark mutates stars/labels per the user's Settings choice, and finish advances the last-check watermark, which changes future read results. It also lists failure modes (unknown action, missing saved login, server login refusal). With destructiveHint=false but real state mutation, this is exactly the context an agent 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-loaded with a one-line purpose, then cleanly sectioned into Use/Behavior/Returns/Errors, so an agent can scan to the part it needs. It is dense and parenthetical-heavy, and the Returns block is long, though that length is largely licensed by the absence of an 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?

For a four-mode state machine with no output schema, the definition covers sequencing, authentication requirements, mutation semantics, and the full return shape of each action (plan, email list with field names and ordering, mail_action, last_check). Errors are enumerated, so nothing material is missing before a call.

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 already 100%, so baseline is 3; the description adds value by tying parameters to the state machine (mark depends on an email id returned by read, and the mark supplants the freeapply_record_outcome kind), which the schema alone does not connect. It stops short of restating per-parameter requirements, so it is incremental rather than exhaustive.

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

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

States a concrete verb and resource ("Runs one email reply check") and explicitly names the coupled sibling freeapply_record_outcome for recording each found email, so the boundary is clear without opening any schema. It also names the two mailbox paths (freeapply reader vs Gmail connector), which distinguishes it from the account/settings tools in the sibling list.

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 "Use:" line gives an explicit ordered protocol — start first, then read via freeapply reader or the Gmail connector, mark after each read email is recorded, finish once everything found is recorded. Exclusions are stated too (finish "only after recording everything found"), leaving nothing 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?

Goes well beyond annotations: explains that without save nothing changes, a passing letter becomes a PDF kept with the job, a failing letter is never saved, saving again replaces the file, saving is refused once the job is applied, and claims are mostly unsupported until setup has stored the résumé text. It also names the specific checks (skills, tools, numbers, claims) and the error conditions.

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

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

Well structured with labeled Use, Behavior, Returns and Errors sections. Despite being long, every section front-loads the decision-relevant information and no sentence is wasted.

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

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

With no output schema, the description fully compensates by documenting the return shape ({ok, problems}, keywords, file, note) and the error cases. Combined with the detailed usage and behavior sections, 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 100%, so the baseline is 3. The description still adds useful cross-parameter constraints: save requires kind cover_letter and job_id, company is the fallback when job_id is absent, and job_id activates keyword analysis and treats posting facts as supported.

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: checks a cover letter or free-text answer against the user's real facts and optionally saves a passing cover letter as a PDF. It explicitly distinguishes itself from freeapply_update_job ('only records') and from short settings-derived fields, so an agent can route correctly 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?

Provides explicit timing ('before typing any written answer or attaching any letter, and after each fix') and explicit exclusions ('Not for short fields straight from settings (name, date, yes/no)'), plus names the sibling that only records. No inference 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?

Annotations only cover the generic mutation/safety profile, but the description supplies the full decision cascade (already tracked, disallowed/signed-out/paused site, repost match, pay-floor skip), the return shape {job_id, existing, status, rule, earlier} with the meaning of 'earlier' and 'restart', and the missing title/company error. It also discloses the idempotence-like safe-repeat property, which is a mild tension with idempotentHint=false but reads as clarifying the actual state behavior rather than contradicting it.

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 usage, then a clearly labeled 'Behavior, first match wins' block that prioritizes rules over prose. The telegraphic colon-chained style packs value but is dense enough that an agent must parse carefully to find the branch it 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?

For a 16-parameter mutation tool with no output schema, the description covers the refusal conditions, the effective return contract including the 'earlier' list and 'restart' flag, and error behavior. Nothing an agent needs in order to call it correctly and interpret the result appears to be 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 100%, so the baseline is 3, but the description adds real meaning: it explains how status=skipped plus status_note are used together for reviewed-but-unpursued jobs, and how posted pay feeds the pay_floor rule outcome. It stops short of walking through the remaining optional posting fields, which the schema already documents well.

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 up front ('Claims a job before you work on it') plus the immediate side effects (duplicate check, rules, tracking) and the returned job_id. It also names what it is not by pointing to freeapply_list_jobs for listing and freeapply_update_job for changing, so it is distinguishable from every sibling 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 explicit when-to-use ('before opening any application form'), a secondary use case (recording a reviewed job not pursued via status skipped + status_note), and an explicit exclusion ('Not for a job already claimed'). Alternative tools are named for the adjacent operations, leaving nothing 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?

With annotations already declaring non-read-only, non-idempotent, and non-destructive behavior, the description adds substantial stateful context: rate limits, daily caps, 15-minute clearance expiry, one-job scope, method-specific counting, and auto-run Stop/restart semantics. These details go well beyond what the annotations provide.

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

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

The description is dense and well-structured with Use, Behavior, Parameters, and Returns sections, and the core purpose is front-loaded. It is somewhat long and repeats the 'right before submit' timing in the opening and Use section, but the length is largely justified by the tool's stateful complexity.

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 complex, non-idempotent stateful tool with no output schema, the description is complete enough: it explains preconditions, rate limits, parameter effects, return fields, and how to react to clear=false, refused, stop_run, and restart outcomes.

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

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

Schema coverage is 100%, but the description still adds meaningful semantics: job_id ties clearance to one job and without it only pace is visible; method affects pace/daily cap and easy_apply requires one-click apply enabled; run_id only applies in auto-run and activates Stop/limits and run check-in 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 states a specific action and resource: a go-ahead/clearance for one submit, checked against pace, user limits, and auto-run Stop state. It also distinguishes itself from freeapply_update_job by noting that job update refuses 'applied' without this clearance.

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 explicit timing and exclusions: use right before every submit, with job_id, not early, and not for a job that will not be submitted now. It also routes stop_run handling to freeapply_manage_autorun action finish.

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 cover read-only/idempotent/open-world, but the description adds substantive behavior: one web request, which sites use public APIs vs. page text, refusal of localhost/private-network addresses and redirects to them, and session-level caching so freeapply_claim_job retains keywords. It also specifies error behavior and recovery ("read it in the browser").

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?

Labeled sections (Use / Behavior / Parameters / Returns / Errors / Next) make it scannable and the critical routing guidance is front-loaded. It is long, and the token-cost aside ("Costs few tokens next to the browser...") is the least essential sentence, though it does reinforce the browser-vs-tool split.

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 annotations covering returns, the description fully carries that burden: it enumerates every returned field including items, suggested_answers provenance, and the keywords/coverage semantics with usage rules ("use matched in the posting's words, never claim missing"). Errors and the natural next tool are also documented.

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

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

Schema coverage is 100% so the baseline is 3; the description goes beyond it by explaining that max_chars caps only the description and that description_chars signals truncation, and by explaining what `source` functionally does (selects saved answers for that site). The url semantics are merely restated ("the posting or its application form"), which is already in 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?

States a specific verb and resource ("Fetches one job posting") plus exactly what is returned (description, form questions, suggested answers, skills asked). It also disambiguates from siblings by naming freeapply_claim_job as the next step and clarifying that search happens in the browser, not here.

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 when-to-use ("read each posting you found before scoring or applying") and explicit when-not ("Not for search-result or sign-in pages: read those in the browser"), plus the key constraint that FreeApply has no job search of its own. It routes to the correct alternative for the excluded cases.

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, so the bar is lower, but the description still adds substantial context beyond them: the data source (accounts the user records on the dashboard's Needs you tab), the authentication boundary (no passwords stored), and the two branch outcomes with concrete field names.

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?

Labeled sections (Use / Behavior / Parameters / Returns / Errors) make it scannable and the purpose is front-loaded. It is dense and slightly long, but nearly every clause carries actionable information; only the returns-section next-step guidance 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?

With no output schema, the description supplies the return shapes for both branches (account object fields vs. {domain, account: null}), the follow-up action for each, and the error condition. Nothing an agent needs to invoke or 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 coverage is 100% (baseline 3), but the description adds genuinely new meaning: the input is normalized to the domain with 'www.' stripped and matched exactly, so careers.example.com and example.com are distinct — and it tells the agent which one to pass. That is exactly the failure mode an agent would otherwise hit.

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?

First sentence states a specific question the tool answers: whether the user already has an employer careers-site account and with which email. It scopes the resource explicitly ('Employer sites only') and names the excluded class (job boards like LinkedIn) plus the sibling that handles 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 an explicit trigger ('when an application form asks you to sign in or create an account') and an explicit exclusion ('Not for signing in or up: FreeApply stores no passwords and you never type one'). It also names freeapply_report_site_problem for job boards and freeapply_update_job for the not-found branch, so alternatives are fully routed.

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' read-only/idempotent hints, it discloses security context ('never includes installation secrets'), an epistemic constraint ('the only source of facts about the user: never invent beyond it'), and critical gating behavior: while `missing` is non-empty, 'apply nowhere' and the agent should open the settings tab. It also describes error behavior for unknown sections.

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 and broken into labeled segments (Use, Behavior, Parameters, Returns, Errors), with no wasted sections. It is dense but mostly earns its length; the sentence 'With the résumé text and the user's own words, the only source of facts about the user: never invent beyond it' is slightly awkward and could be clearer.

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

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

For a one-parameter read tool with rich annotations but no output schema, the description covers everything an agent needs: return shape ({settings, missing}), the full section list, missing-field gating, and error handling. Nothing material is missing to call or 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?

The schema already documents the `sections` parameter at 100% coverage, so the baseline is 3. The description significantly adds meaning by enumerating valid section names under Returns, advising to request only what the step needs with a concrete example, and warning that `resume` is the largest and should be omitted unless its text is required.

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: 'Reads the user's settings: who they are, what they seek and how FreeApply should work.' It explicitly distinguishes itself from freeapply_manage_answers, freeapply_get_status, and freeapply_update_settings, so an agent can route correctly 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?

It gives explicit timing: 'once per session or helper, and again after each auto-run go, before scoring jobs or filling a form.' It also names the alternatives for single-form answers and status checks, and directs changes to freeapply_update_settings. When and when-not are both covered.

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 still adds value beyond them: 'counted fresh from the local database each call, nothing cached' discloses cost and data freshness, which annotations cannot express. It also defines a non-obvious metric inline ('response_rate – % of applications with a real reply; automatic acknowledgements not counted') and clarifies last_reply_check.

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 a one-line purpose, then labeled Use/Behavior/Returns blocks. The Returns enumeration is long but each field grouping (counts, rates, aggregations) earns its place because no output schema exists. Slightly dense, but structured rather than rambling.

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 what comes back, and it does so field-by-field including units (percent) and semantics (needs_you = jobs waiting on the user; daily = applications per day). Combined with cost/freshness disclosure, an agent has everything needed to call and interpret it.

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

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

Zero parameters, so the schema carries nothing to explain; the description correctly states 'No parameters', removing any question about required filters. It stops there rather than adding semantics a parameterless tool would need, which is appropriate.

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 concrete verb+resource framing ('The user's job search in numbers: applications, replies, interviews, offers, rates') and immediately names the two siblings it is not (freeapply_list_jobs, freeapply_get_status). An agent can distinguish this from list_jobs and get_status without opening any schema.

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

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

Explicit usage section: 'Use: to report progress, e.g. when wrapping up a session. Not for finding a particular job.' Both a positive trigger and an exclusion are stated, and the alternative for per-job lookups is named. Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/destructive=false, but the description adds substantial non-obvious behavior: wait can hold up to 10 minutes until Terms are accepted, returns within seconds of completion, and it discloses what setup state is reported. It also explains wait_again semantics for a timed-out wait.

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?

Structure is excellent — purpose, use, behavior, parameters, returns, and next steps are clearly separated and front-loaded. It is dense and the Returns enumeration is long, but almost every clause carries actionable information for a complex tool; minor verbosity only.

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 explain returns — and it does thoroughly, enumerating the workflow, terms, setup, sites, documents, and procedure fields. It also provides failure-branch guidance (workflow.ok false → stop; terms/setup false → freeapply-setup; rescan → models step), making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description materially adds meaning: 'lane (with procedure freeapply-apply) is for a helper: only the hard rules and that lane's steps,' which explains an interaction constraint the schema does not. It doesn't fully enumerate each param's individual effect, but the added interaction semantics push it above baseline.

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

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

The opening line states a specific dual purpose: reporting whether FreeApply can work now and returning a signed step-by-step procedure. It also explicitly disambiguates from siblings by naming freeapply_get_settings (user details) and freeapply_get_stats (job search), so an agent can route 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?

Usage is prescriptive: 'first in every session and before each task,' and use the wait flag after asking the user to accept Terms or finish setup. It even notes it works while locked/unaccepted, so its purpose as a diagnostic tool is unambiguous.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the 'read-only' line is redundant, but the description goes well beyond them: filter combination is AND across all given params, pagination preserves the same ordering with a short-page-means-last rule, and empty results are specified for both no-match and unknown job_id. That is the kind of behavioral detail annotations cannot express.

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

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

Front-loaded with purpose, then clearly segmented into Use / Behavior / Parameters / Returns, with zero filler. The enumerated 21-field return list is long, but it substitutes for a missing output schema, so it earns its space; only the restated defaults are pure repetition.

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

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

With no output schema, the field-level return list is exactly what an agent needs to know what it will get back, and ordering, filtering, pagination limits, and empty-result behavior are all covered. Nothing an agent needs to invoke 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 100%, so the baseline would be 3; the description earns above that by adding semantics the schema lacks — 'search' is scoped to title, company or location and is case-insensitive, job_id returns empty (not an error) when unknown, and status/outcome are exact matches. The default-200/offset-0 behavior is restated rather than added, keeping it off 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?

States a specific verb and resource ('Lists the user's tracked jobs') plus the exact ordering rule (submitted, else updated, else found). It explicitly separates itself from freeapply_get_stats (totals/rates) and freeapply_claim_job / freeapply_update_job (mutation), so an agent can route correctly 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?

A dedicated 'Use:' clause enumerates the three concrete jobs this serves (find a job_id, look up one job, answer questions about particular jobs), and a 'Not for' clause names the sibling tools that handle adding/changing plus notes that removal happens in the dashboard. Both the positive and negative routing conditions are explicit.

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 save replaces the answer under the same question and that an empty answer removes it, which explains the destructiveHint=true and idempotentHint=true flags in concrete terms. It also warns that saved answers count as facts in freeapply_check_text, a downstream effect an agent could not infer, and lists error conditions.

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 verb+resource, then organizes the rest into labeled Use/Behavior/Returns/Errors segments, which is easy to scan. Slightly dense with parenthetical cross-references, but every sentence carries actionable 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 compensates by spelling out both return shapes (job_id, answers, saved_answers, cover_letter for get; label, saved, removed, saved_answers for save) and the error cases. 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 description coverage is 100%, so label, action, answer, and job_id are already fully documented with the same wording ('the user's own words', 'empty removes the saved answer'). The description adds error conditions tied to parameters (get without job_id, save without label) but little semantic detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb pair and resource: gets or saves the user's own answers to specific form questions. It immediately distinguishes itself from freeapply_get_settings (referenced as 'general details') and from freeapply_update_job with status needs_info for brand-new questions.

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 'Use:' sentence gives explicit triggering conditions for each action — get before retrying a re-queued job, save when the user answers in-conversation. It also names the alternative path for a new question (freeapply_update_job status needs_info), so when-not-to-use is covered.

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 annotations by describing the 10-minute wait behavior, takeover semantics, single-runner constraint, check-in requirements, hard-stop behavior via freeapply_clear_to_submit, and finish scheduling. These are critical stateful behaviors for an agent orchestrating the auto-run loop.

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

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

The description is long and dense, but it is structured into purpose, usage, behavior, parameters, returns, and errors. Most sentences carry necessary state-machine semantics, though some parentheticals could be tightened without losing meaning.

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 full control flow for a complex stateful tool: expected returns for go true/false branches, needs_user handling, replaced/wait_again cases, finish return values, and error conditions. With no output schema, this description provides the return semantics an agent needs.

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

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

Although schema coverage is 100%, the description adds operational meaning: wait holds until something is due, without wait start answers immediately, takeover applies only to the call right after the user asked, run_id is from start, and summary appears in dashboard history. This materially supplements the terse schema descriptions.

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 workflow verb/resource: keeping FreeApply applying automatically via start/finish actions. It explicitly distinguishes itself from freeapply_get_status and from manual user-run sessions, so an agent can identify its role without opening the schema.

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

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

Provides explicit usage sequencing: start with wait, finish after each run, then start again, as part of setup's auto-run mode. It also says when not to use it (a session the user runs by hand) and names freeapply_get_status as the state-only alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive/non-open-world, but the description adds real context beyond them: no data is changed, the dashboard is started on demand with a port fallback (127.0.0.1:7878 or next free port), and it is reachable only from this machine. It also discloses the two failure modes and what the agent should do in each.

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 organized under Use:/Behavior:/Parameters:/Returns: labels so an agent can scan to the section it needs. Dense rather than padded — no sentence repeats a structured field verbatim, and the Returns guidance is load-bearing because 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?

Though no output schema exists, the description documents the return shape ({url, opened}) and the meaning of each degenerate case, plus the localhost-only constraint and side effects. Nothing needed to invoke it correctly or interpret the result is missing for a single optional-enum-parameter 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 already 100% with an enum, so the baseline is 3, but the description goes further by explaining what each enum value actually surfaces — overview (default; shows the Terms until accepted), settings, issues ("Needs you"), applications, replies. That is meaning the schema does not carry, and it matters for choosing a tab.

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 ("opens the local FreeApply dashboard in the user's browser") and immediately delimits it against the nearest sibling: freeapply_get_status only reports the URL while this one actually opens a tab. An agent can pick between the two without opening either schema.

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

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

Explicit when-to-use list ("when the user must act there: accept the Terms, fill settings, answer questions waiting on them, review applications and replies") paired with an explicit exclusion ("Not for reading data: other tools return it"). Both the selection condition and the anti-pattern 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?

Beyond the annotations, it explains the rank-based outcome update rule, duplicate-email idempotency, exact-setting behavior without an email, return shapes, and error cases. These details materially help the agent understand side effects and 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 description is dense but well structured with Use, Behavior, Returns, and Errors sections. It front-loads the core purpose and avoids wasting space on restating schema details.

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

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

Given 10 parameters, no output schema, and non-trivial conditional behavior, the description covers usage, side effects, returns, and errors adequately. An agent has enough information to call it correctly in both email and non-email modes.

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?

Although schema coverage is already 100%, the description adds crucial conditional semantics: with gmail_message_id the outcome is rank-gated, without it the outcome is set exactly, and job_id has different implications in each mode. It also explains what the email fields contribute to the dashboard.

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

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

The description states a specific verb and resource: recording what an employer did with an application. It also explicitly distinguishes this from the user's own application steps, naming freeapply_update_job as the tool for that.

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 explicit trigger conditions: for each employer email found during a reply check, and when the user reports a call or corrects an outcome. It also states what the tool is not for and routes that case to freeapply_update_job.

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 explains the per-status consequences (unavailable until the user signs in and confirms; paused until midnight), the downstream effect on freeapply_claim_job, and that re-reporting is a no-op and only the user can restore readiness. That gives the agent the lifecycle and side effects of a destructiveHint=true mutation, which the annotations alone do 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 action, then labeled Use/Behavior/Returns/Errors sections, with no filler sentences. The telegraphic, colon-heavy style is dense but each line 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?

Fills the gap left by the absent output schema by documenting the return shape {site, status, sites} and names the error case (a site the user didn't choose). Combined with the state-transition details, 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?

Schema coverage is 100% and both parameters are fully described in the schema, including enum meanings and example phrasing for limit_reached. The description adds only illustrative site examples and the note that only user-chosen sites are valid, so baseline 3 is right.

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 (marks a chosen job site unusable) with the concrete trigger conditions (signed out or daily limit). It also distinguishes the employer-careers case by routing to freeapply_find_site_account, so an agent can separate this from sibling tools 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 an explicit trigger ('as soon as a chosen site shows a sign-in page or a daily limit'), the required follow-up behavior ('keep applying on the ready sites or company career sites'), and a hard exclusion ('Never type a password'). Alternatives are named rather than implied.

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

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

The description adds substantial context beyond the annotations: preview sends nothing, sync transmits only what current choices allow, cannot be undone from here, and is refused moments after a previous sync (a debounce the idempotentHint does not convey). It also enumerates sync failure reasons (terms not accepted, recent sync, server unreachable). It stops short of explaining auth/permission requirements, which keeps it at 4.

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

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

Front-loaded with the core sentence, then cleanly labeled Use/Behavior/Returns/Errors sections so an agent can skim. It is dense and long for a one-parameter tool, but nearly every sentence carries operational content rather than filler.

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

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

There is no output schema, and the description compensates by describing the return payload for both modes, including windowing of secrets and the conditional talent-pool request. Error behavior and the side effect of sync over the network are also covered, leaving nothing essential 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 100% schema coverage on a single enum parameter the baseline is 3, but the description goes further by tying each value to a usage rule and a distinct return shape. The only gap is that it does not repeat the enum syntax, which the schema already handles.

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 the exact resource (the data the user chose to share) and distinguishes its two modes, preview and sync, in the very first sentence. It explicitly routes away from freeapply_get_settings for the choices themselves, so an agent can separate it from that sibling 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?

Use conditions are spelled out per mode: preview when the user asks what is shared, sync only when the user asks to send now. It also names what this tool is NOT for (changing choices) and where that happens instead (dashboard Settings, Data sharing).

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 annotations, the description discloses key behavior: status replacement, fresh clearance enforcement for applied, truthfulness checks on cover_text, the rule that applied jobs only the user can change, needs_info re-queue behavior, and refusal rules for status-specific fields. It also describes return fields and error conditions, giving the agent operational context needed to invoke it safely.

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 and organized into clear Use, Behavior, Returns, and Errors sections. Despite its length, every section earns its place by covering a complex multi-status tool with 11 parameters.

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 supplies the relevant return shape and error behavior. Combined with annotations and full schema coverage, it gives enough information for an agent to call the tool correctly across statuses and edge cases.

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

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

Schema description coverage is 100%, so the schema already carries most parameter meaning and baseline is 3. The description adds conditional semantics beyond the schema, such as applied-only enforcement, needs_info question handling, needs_account sign-up page behavior, and refusal when a field is supplied for the wrong status.

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: it sets a claimed job's application status. It immediately distinguishes the tool from siblings by naming freeapply_record_outcome for employer responses and freeapply_claim_job for adding jobs, so an agent can identify the correct tool 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 explicitly maps statuses to situations: applied after submit, skipped/failed when giving up, needs_info/needs_account/blocked when the user must act. It also names alternative tools for adjacent operations, leaving little ambiguity about when to use this tool versus 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 mark it destructive and idempotent, and the description adds substantial operational context: overwrites without undo, deep-merge semantics, whole-list replacement, skipped user-only sections listed in ignored, and all-or-nothing saves. It also describes error behavior where the message names every problem.

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?

It is dense but organized into clear operational clauses: Changes, Use, Behavior, Parameters, Returns, and Errors. The purpose and usage are front-loaded, and each section carries distinct information needed for a complex nested update tool rather than repeating structured fields.

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 nested update tool with no output schema, the description covers return fields (changed, ignored, setup_complete, missing, and models after a scan) and the main error cases. Combined with merge and skipped-section behavior, it is complete enough for an agent to invoke 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?

The schema only says patch is an object nested by section. The description supplies the actual section names, an example patch, the writable fields, résumé and model-scan restrictions, and validation constraints such as cover_letter.length choices, which is far beyond what the schema provides.

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

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

States the specific resource (user settings) and the three content areas it saves: stated facts/preferences, résumé text and profile, and the AI model scan. It also names freeapply_get_settings for reading and freeapply_manage_answers for single form answers, distinguishing it from those 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?

Explicitly says when to use it: when the user states a fact or preference, during setup's résumé step, or in the AI models step. It also gives a clear when-not rule: never fill a field the user did not provide, and routes reading to freeapply_get_settings and single answers to freeapply_manage_answers.

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